/ Hex Artifact Content
Login

Artifact c3b1782d1a290253b37ebc999c42e894ff8aa9f76526b2938df2f8939d20de39:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5240: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5280: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5540: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5550: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55b0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55d0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55f0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5600: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5610: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5620: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5630: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5640: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5650: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5670: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5680: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5690: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56b0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
56c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56d0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
56e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56f0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5700: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5710: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5730: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5740: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5750: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5770: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5780: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5790: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
57a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57b0: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
57c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57d0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
57e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57f0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5800: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5810: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5830: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5850: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5870: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5890: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
58a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58b0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
58c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58d0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
58e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58f0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
5900: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5910: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5930: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
5940: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5950: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5970: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5980: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5990: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
59a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
59b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
59c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
59d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
59f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a10: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5a30: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5a50: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5a70: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5a90: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ab0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5ac0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ad0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5b00: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5b10: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5b20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b30: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5b40: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5b50: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5b60: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5b70: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5b80: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5b90: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5ba0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5bb0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5bc0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5bd0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5be0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5bf0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5c00: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5c10: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5c20: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5c40: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5c60: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5c80: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5c90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5ca0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5cc0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e 49 54  EADONLY_CANTINIT
5cd0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5ce0: 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c 38 29  EADONLY | (5<<8)
5cf0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5d00: 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45 43 54  _READONLY_DIRECT
5d10: 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49 54 45  ORY      (SQLITE
5d20: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36 3c 3c  _READONLY | (6<<
5d30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d40: 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43  TE_ABORT_ROLLBAC
5d50: 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  K          (SQLI
5d60: 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38  TE_ABORT | (2<<8
5d70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45  E_CONSTRAINT_CHE
5d90: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  CK        (SQLIT
5da0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5db0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5dc0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5dd0: 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53  _COMMITHOOK   (S
5de0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5df0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5e00: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5e10: 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20  AINT_FOREIGNKEY 
5e20: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5e30: 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23  AINT | (3<<8)).#
5e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5e50: 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f  NSTRAINT_FUNCTIO
5e60: 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  N     (SQLITE_CO
5e70: 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38  NSTRAINT | (4<<8
5e80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5e90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54  E_CONSTRAINT_NOT
5ea0: 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54  NULL      (SQLIT
5eb0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ec0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5ed0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ee0: 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53  _PRIMARYKEY   (S
5ef0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5f00: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5f10: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5f20: 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20  AINT_TRIGGER    
5f30: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5f40: 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23  AINT | (7<<8)).#
5f50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5f60: 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20  NSTRAINT_UNIQUE 
5f70: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5f80: 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38  NSTRAINT | (8<<8
5f90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5fa0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41  E_CONSTRAINT_VTA
5fb0: 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  B         (SQLIT
5fc0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5fd0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
5fe0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ff0: 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53  _ROWID        (S
6000: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6010: 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69   |(10<<8)).#defi
6020: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
6030: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20  _RECOVER_WAL    
6040: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45    (SQLITE_NOTICE
6050: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
6060: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
6070: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43  _RECOVER_ROLLBAC
6080: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  K (SQLITE_NOTICE
6090: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
60a0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
60b0: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20  G_AUTOINDEX     
60c0: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e    (SQLITE_WARNIN
60d0: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  G | (1<<8)).#def
60e0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f  ine SQLITE_AUTH_
60f0: 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20  USER            
6100: 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20     (SQLITE_AUTH 
6110: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
6120: 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44  e SQLITE_OK_LOAD
6130: 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20  _PERMANENTLY    
6140: 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31   (SQLITE_OK | (1
6150: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
6160: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
6170: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
6180: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
6190: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
61a0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
61b0: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
61c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
61d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
61e0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
61f0: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
6200: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
6210: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6220: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
6230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6240: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
6250: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
6260: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6270: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6290: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
62a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
62b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
62c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
62d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
62e0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
62f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6300: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6310: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6320: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6330: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
6340: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
6350: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6370: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
6380: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6390: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
63a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63b0: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
63c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
63d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
63e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63f0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
6400: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
6410: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6420: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6440: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
6450: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
6460: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6470: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6490: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
64a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
64b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
64c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
64d0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
64e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
64f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6510: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
6520: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
6530: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6550: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
6560: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
6570: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6590: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
65a0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
65b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
65c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
65d0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
65e0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
65f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6610: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
6620: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
6630: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6650: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
6660: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
6670: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6680: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
66a0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
66b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
66c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
66d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
66e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
66f0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
6700: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
6710: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6720: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6730: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6740: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
6750: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
6760: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6770: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6790: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
67a0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
67b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
67c0: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
67d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
67e0: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
67f0: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
6800: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
6810: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
6820: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
6830: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
6840: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
6850: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6860: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
6870: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
6880: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
6890: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
68a0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
68b0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
68c0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
68d0: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
68e0: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
68f0: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
6900: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6910: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
6920: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
6930: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6940: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
6950: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
6960: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
6970: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6990: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
69a0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
69b0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
69c0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
69d0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
69e0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
69f0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
6a00: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
6a10: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
6a20: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6a30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6a40: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
6a50: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
6a60: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
6a70: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
6a80: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
6a90: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
6aa0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
6ab0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
6ac0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
6ad0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
6ae0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6af0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6b00: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6b10: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
6b20: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
6b30: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
6b40: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
6b50: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
6b60: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6b70: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
6b80: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
6b90: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
6ba0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
6bb0: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
6bc0: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
6bd0: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
6be0: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
6bf0: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
6c00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
6c10: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
6c20: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
6c30: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
6c40: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
6c50: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
6c60: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
6c70: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
6c80: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49  anged.  The SQLI
6c90: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
6ca0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a  ABLE_WHEN_OPEN.*
6cb0: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73  * flag indicates
6cc0: 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e   that a file can
6cd0: 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77  not be deleted w
6ce0: 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a  hen open.  The.*
6cf0: 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  * SQLITE_IOCAP_I
6d00: 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e  MMUTABLE flag in
6d10: 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
6d20: 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72   file is on.** r
6d30: 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61  ead-only media a
6d40: 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  nd cannot be cha
6d50: 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f  nged even by pro
6d60: 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65  cesses with.** e
6d70: 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67  levated privileg
6d80: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  es..**.** The SQ
6d90: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
6da0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6db0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
6dc0: 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66 69  underlying.** fi
6dd0: 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74  lesystem support
6de0: 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c 65  s doing multiple
6df0: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
6e00: 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68 65  s atomically whe
6e10: 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74 65  n those.** write
6e20: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6e30: 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b 53 51  bracketed by [SQ
6e40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
6e50: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 61  _ATOMIC_WRITE] a
6e60: 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  nd.** [SQLITE_FC
6e70: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
6e80: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64 65  C_WRITE]..*/.#de
6e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ea0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
6eb0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6ec0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6ed0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6ee0: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6ef0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6f00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6f10: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6f20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6f30: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6f40: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
6f50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6f60: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
6f70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6f80: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
6f90: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
6fa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6fb0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
6fc0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6fd0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6fe0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6ff0: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
7000: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
7010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7020: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
7030: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7040: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
7050: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7060: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
7070: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
7080: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7090: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
70a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
70b0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
70c0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
70d0: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
70e0: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
70f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
7100: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
7110: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
7120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7130: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
7140: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
7150: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
7160: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
7170: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
7180: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23      0x00002000.#
7190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
71a0: 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43  CAP_BATCH_ATOMIC
71b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
71c0: 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  04000../*.** CAP
71d0: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
71e0: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a  ing Levels.**.**
71f0: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65   SQLite uses one
7200: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
7210: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
7220: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
7230: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d  nt to calls it m
7240: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63  akes to the xLoc
7250: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
7260: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ) methods.** of 
7270: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
7280: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a  ethods] object..
7290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
72a0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20  E_LOCK_NONE     
72b0: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
72c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
72d0: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  D        1.#defi
72e0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  ne SQLITE_LOCK_R
72f0: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23  ESERVED      2.#
7300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
7310: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20  CK_PENDING      
7320: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
7330: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7340: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41       4../*.** CA
7350: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e  PI3REF: Synchron
7360: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61  ization Type Fla
7370: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51  gs.**.** When SQ
7380: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  Lite invokes the
7390: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20   xSync() method 
73a0: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  of an.** [sqlite
73b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
73c0: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63  ject it uses a c
73d0: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
73e0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
73f0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
7400: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ond argument..**
7410: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c  .** When the SQL
7420: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7430: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20  Y flag is used, 
7440: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
7450: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74  e.** sync operat
7460: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  ion only needs t
7470: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20  o flush data to 
7480: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49  mass storage.  I
7490: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  node.** informat
74a0: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  ion need not be 
74b0: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20  flushed. If the 
74c0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
74d0: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65  of the flag.** e
74e0: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
74f0: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65  _NORMAL, that me
7500: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  ans to use norma
7510: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
7520: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c  ics..** If the l
7530: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65  ower four bits e
7540: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
7550: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e  _FULL, that mean
7560: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20  s.** to use Mac 
7570: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7580: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
7590: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f  sync()..**.** Do
75a0: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65   not confuse the
75b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
75c0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
75d0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a  YNC_FULL flags.*
75e0: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47  * with the [PRAG
75f0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7600: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47  NORMAL and [PRAG
7610: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7620: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73  FULL.** settings
7630: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e  .  The [synchron
7640: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65  ous pragma] dete
7650: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c  rmines when call
7660: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e  s to the.** xSyn
7670: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63  c VFS method occ
7680: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75  ur and applies u
7690: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20  niformly across 
76a0: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  all platforms..*
76b0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  * The SQLITE_SYN
76c0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
76d0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
76e0: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f  ags determine ho
76f0: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f  w.** energetic o
7700: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f  r rigorous or fo
7710: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20  rceful the sync 
7720: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61  operations are a
7730: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20  nd.** only make 
7740: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20  a difference on 
7750: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20  Mac OSX for the 
7760: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63  default SQLite c
7770: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70  ode..** (Third-p
7780: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65  arty VFS impleme
7790: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61  ntations might a
77a0: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73  lso make the dis
77b0: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
77c0: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  een SQLITE_SYNC_
77d0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
77e0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74  E_SYNC_FULL, but
77f0: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70   among the.** op
7800: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20  erating systems 
7810: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74  natively support
7820: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e  ed by SQLite, on
7830: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61  ly Mac OSX.** ca
7840: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69  res about the di
7850: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64  fference.).*/.#d
7860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7870: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
7880: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
7890: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
78a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
78b0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
78c0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
78d0: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
78e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
78f0: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
7900: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  ile Handle.**.**
7910: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   An [sqlite3_fil
7920: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  e] object repres
7930: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c  ents an open fil
7940: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71  e in the .** [sq
7950: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69  lite3_vfs | OS i
7960: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e  nterface layer].
7970: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
7980: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70  interface.** imp
7990: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
79a0: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62  l.** want to sub
79b0: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63  class this objec
79c0: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  t by appending a
79d0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
79e0: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77  .** for their ow
79f0: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74  n use.  The pMet
7a00: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20  hods entry is a 
7a10: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
7a20: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7a30: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  hods] object tha
7a40: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64  t defines method
7a50: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67  s for performing
7a60: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  .** I/O operatio
7a70: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66  ns on the open f
7a80: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ile..*/.typedef 
7a90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
7aa0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  ile sqlite3_file
7ab0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7ac0: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20  _file {.  const 
7ad0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7ae0: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68  o_methods *pMeth
7af0: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73  ods;  /* Methods
7b00: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c   for an open fil
7b10: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.};../*.** C
7b20: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7b30: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75  rface File Virtu
7b40: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  al Methods Objec
7b50: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  t.**.** Every fi
7b60: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
7b70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7b80: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75  pen] method popu
7b90: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c  lates an.** [sql
7ba0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7bb0: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d  t (or, more comm
7bc0: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73  only, a subclass
7bd0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
7be0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7bf0: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
7c00: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
7c10: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a  of this object..
7c20: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  ** This object d
7c30: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f  efines the metho
7c40: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
7c50: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
7c60: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74  tions.** against
7c70: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72   the open file r
7c80: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68  epresented by th
7c90: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
7ca0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
7cb0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
7cc0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7cd0: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
7ce0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7cf0: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
7d00: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
7d10: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
7d20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
7d30: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
7d40: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
7d50: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69  ven if the [sqli
7d60: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72  te3_vfs.xOpen] r
7d70: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20  eported that it 
7d80: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  failed.  The.** 
7d90: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76  only way to prev
7da0: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43  ent a call to xC
7db0: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  lose following a
7dc0: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33   failed [sqlite3
7dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69  _vfs.xOpen].** i
7de0: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  s for the [sqlit
7df0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f  e3_vfs.xOpen] to
7e00: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
7e10: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7e20: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c  lement.** to NUL
7e30: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
7e40: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
7e50: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
7e60: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
7e70: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
7e80: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
7e90: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
7ea0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
7eb0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
7ec0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
7ed0: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
7ee0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
7ef0: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
7f00: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
7f10: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
7f20: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
7f30: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
7f40: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
7f50: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
7f60: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
7f70: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
7f80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
7f90: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
7fa0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
7fb0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
7fc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
7fd0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
7fe0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7ff0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
8000: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8010: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
8020: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
8030: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
8040: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8050: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
8060: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
8070: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
8080: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
8090: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
80a0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
80b0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
80c0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
80d0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
80e0: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
80f0: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
8100: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
8110: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
8120: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
8130: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
8140: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
8150: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
8160: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
8170: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
8180: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
8190: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
81a0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
81b0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
81c0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
81d0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
81e0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
81f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
8200: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
8210: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
8220: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
8230: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8240: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
8250: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
8260: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
8270: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
8280: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
8290: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
82a0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
82b0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
82c0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
82d0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
82e0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
82f0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
8300: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
8310: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
8320: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
8330: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
8340: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
8350: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
8360: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
8370: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
8380: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
8390: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
83a0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
83b0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
83c0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
83d0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
83e0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
83f0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
8400: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
8410: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
8420: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
8430: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
8440: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
8450: 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  [file control op
8460: 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20  codes | list of 
8470: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
8480: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
8490: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
84a0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
84b0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
84c0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
84d0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
84e0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
84f0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
8500: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
8510: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
8520: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
8530: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
8540: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
8550: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
8560: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
8570: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
8580: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
8590: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
85a0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
85b0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
85c0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
85d0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
85e0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
85f0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
8600: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
8610: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
8620: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
8630: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
8640: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
8650: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
8660: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
8670: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
8680: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
8690: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
86a0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
86b0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
86c0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
86d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
86e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
86f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
8700: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8710: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
8720: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8730: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
8740: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8750: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
8760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8770: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
8780: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8790: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
87a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
87b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
87c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
87d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
87e0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
87f0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8800: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
8810: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
8820: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  UENTIAL].** <li>
8830: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55   [SQLITE_IOCAP_U
8840: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
8850: 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OPEN].** <li> [S
8860: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
8870: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
8880: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8890: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
88a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
88b0: 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54  E_IOCAP_BATCH_AT
88c0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  OMIC].** </ul>.*
88d0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
88e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
88f0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8900: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
8910: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
8920: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
8930: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
8940: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
8950: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
8960: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
8970: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
8980: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
8990: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
89a0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
89b0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
89c0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
89d0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
89e0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
89f0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
8a00: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
8a10: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
8a20: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
8a30: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
8a40: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
8a50: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
8a60: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
8a70: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
8a80: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
8a90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8aa0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
8ab0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
8ac0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
8ad0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
8ae0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
8af0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
8b00: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
8b10: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
8b20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
8b30: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
8b40: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
8b50: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
8b60: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
8b70: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
8b80: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
8b90: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
8ba0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8bb0: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
8bc0: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
8bd0: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
8be0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8bf0: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
8c00: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
8c10: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
8c20: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
8c30: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8c40: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
8c50: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
8c60: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8c70: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
8c80: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
8c90: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
8ca0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8cb0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
8cc0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
8cd0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8ce0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8cf0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
8d00: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
8d10: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
8d20: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8d30: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8d40: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
8d50: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8d60: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
8d70: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
8d80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8d90: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
8da0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
8db0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8dc0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
8dd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
8de0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8df0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8e00: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
8e10: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8e20: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
8e30: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
8e40: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
8e50: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8e60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
8e70: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8e80: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
8e90: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
8ea0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
8eb0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
8ec0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8ed0: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
8ee0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
8ef0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8f00: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
8f10: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
8f20: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
8f30: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
8f40: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
8f50: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
8f60: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
8f70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8f80: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
8f90: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8fa0: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
8fb0: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
8fc0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8fd0: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
8fe0: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
8ff0: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
9000: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
9010: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
9020: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65  2 */.  int (*xFe
9030: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
9040: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
9050: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d  4 iOfst, int iAm
9060: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20  t, void **pp);. 
9070: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29   int (*xUnfetch)
9080: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
9090: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
90a0: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20  fst, void *p);. 
90b0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
90c0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
90d0: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f  version 3 */.  /
90e0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
90f0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
9100: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
9110: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
9120: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
9130: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
9140: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59  l Opcodes.** KEY
9150: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e  WORDS: {file con
9160: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66  trol opcodes} {f
9170: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
9180: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  de}.**.** These 
9190: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
91a0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
91b0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
91c0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
91d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
91e0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
91f0: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
9200: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9210: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
9220: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e..**.** <ul>.**
9230: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9240: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a  NTL_LOCKSTATE]].
9250: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9260: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
9270: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
9280: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
9290: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
92a0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
92b0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
92c0: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
92d0: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
92e0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
92f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
9300: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
9310: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
9320: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
9330: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
9340: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
9350: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
9360: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
9370: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
9380: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
9390: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
93a0: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
93b0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
93c0: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c  sting and is onl
93d0: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e  y available when
93e0: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54   the SQLITE_TEST
93f0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
9400: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
9410: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9420: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
9430: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
9440: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9450: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
9460: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
9470: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
9480: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
9490: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
94a0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
94b0: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
94c0: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
94d0: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
94e0: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
94f0: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
9500: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
9510: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
9520: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
9530: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
9540: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
9550: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
9560: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
9570: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
9580: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
9590: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
95a0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
95b0: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
95c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
95d0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
95e0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
95f0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9600: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
9610: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
9620: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
9630: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
9640: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
9650: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
9660: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
9670: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
9680: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
9690: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
96a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
96b0: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
96c0: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
96d0: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
96e0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
96f0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
9700: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
9710: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
9720: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
9730: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
9740: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
9750: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
9760: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
9770: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
9780: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
9790: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
97a0: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
97b0: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
97c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
97d0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
97e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
97f0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9800: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
9810: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
9820: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
9830: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9840: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
9850: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
9860: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
9870: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9880: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
9890: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
98a0: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
98b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
98c0: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
98d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
98e0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
98f0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9900: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9910: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
9920: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9930: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9940: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a  iated with the j
9950: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74  ournal file (eit
9960: 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c  her.** the [roll
9970: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72  back journal] or
9980: 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61   the [write-ahea
9990: 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61  d log]) for a pa
99a0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
99b0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
99c0: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
99d0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
99e0: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
99f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9a00: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
9a10: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
9a20: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
9a30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9a40: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
9a50: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
9a60: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9a70: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9a80: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
9a90: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9aa0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9ab0: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9ac0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9ad0: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
9ae0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
9af0: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
9b00: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
9b10: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
9b20: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
9b30: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
9b40: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
9b50: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9b60: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9b70: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9b80: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
9b90: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9ba0: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9bb0: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9bc0: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9bd0: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
9be0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9bf0: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
9c00: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
9c10: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
9c20: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
9c30: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
9c40: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
9c50: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9c60: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9c70: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9c80: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
9c90: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9ca0: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9cb0: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9cc0: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9cd0: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
9ce0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9cf0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
9d00: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
9d10: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9d20: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9d30: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9d40: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9d50: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9d60: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9d70: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9d80: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9d90: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9da0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9db0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9dc0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9dd0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9de0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9df0: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
9e00: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9e10: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
9e20: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
9e30: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
9e40: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
9e50: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9e60: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9e70: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9e80: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9e90: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9ea0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9eb0: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9ec0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9ed0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9ee0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9ef0: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
9f00: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9f10: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9f20: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9f30: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9f40: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
9f50: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9f60: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9f70: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9f80: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9f90: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9fa0: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9fb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9fc0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9fd0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9fe0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9ff0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
a000: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
a010: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
a020: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
a030: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
a040: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
a050: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
a060: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
a070: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
a080: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
a090: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
a0a0: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
a0b0: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
a0c0: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
a0d0: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
a0e0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
a0f0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
a100: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
a110: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
a120: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
a130: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
a140: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
a150: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
a160: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
a170: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
a180: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
a190: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
a1a0: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
a1b0: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
a1c0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
a1d0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
a1e0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
a1f0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
a200: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
a210: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
a220: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
a230: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
a240: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
a250: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
a260: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a270: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
a280: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
a290: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
a2a0: 20 69 73 20 74 68 65 20 6e 65 77 20 72 65 74 72   is the new retr
a2b0: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
a2c0: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
a2d0: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
a2e0: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
a2f0: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
a300: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
a310: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
a320: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
a330: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
a340: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
a350: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
a360: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
a370: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
a380: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
a390: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
a3a0: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
a3b0: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
a3c0: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
a3d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a3e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
a3f0: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
a400: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
a410: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
a420: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
a430: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
a440: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
a450: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
a460: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
a470: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
a480: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
a490: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
a4a0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a4b0: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
a4c0: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
a4d0: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
a4e0: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
a4f0: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
a500: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
a510: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
a520: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
a530: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
a540: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
a550: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
a560: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
a570: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
a580: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
a590: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
a5a0: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
a5b0: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
a5c0: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
a5d0: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
a5e0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
a5f0: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
a600: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
a610: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
a620: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
a630: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
a640: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
a650: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
a660: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
a670: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
a680: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a690: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a6a0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a6b0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a6c0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a6d0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a6e0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a6f0: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
a700: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
a710: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
a720: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
a730: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a740: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a750: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a760: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a770: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
a780: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
a790: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a7a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a7b0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
a7c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a7d0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a7e0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a7f0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a800: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a810: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
a820: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
a830: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
a840: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
a850: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
a860: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
a870: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
a880: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
a890: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
a8a0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
a8b0: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
a8c0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a8d0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a8e0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a8f0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a900: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a910: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
a920: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
a930: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
a940: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
a950: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a960: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
a970: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a980: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a990: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a9a0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a9b0: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
a9c0: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
a9d0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a9e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a9f0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
aa00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
aa10: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
aa20: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
aa30: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
aa40: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
aa50: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
aa60: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
aa70: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
aa80: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
aa90: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
aaa0: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
aab0: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
aac0: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
aad0: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
aae0: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
aaf0: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
ab00: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
ab10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ab20: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
ab30: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ab40: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
ab50: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
ab60: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
ab70: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
ab80: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
ab90: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
aba0: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
abb0: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
abc0: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
abd0: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
abe0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
abf0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
ac00: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
ac10: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
ac20: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
ac30: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
ac40: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
ac50: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
ac60: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
ac70: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
ac80: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
ac90: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
aca0: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
acb0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
acc0: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
acd0: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
ace0: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
acf0: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
ad00: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
ad10: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
ad20: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
ad30: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
ad40: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
ad50: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
ad60: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
ad70: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
ad80: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
ad90: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
ada0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
adb0: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
adc0: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
add0: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
ade0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
adf0: 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  VFS_POINTER]].**
ae00: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ae10: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d  NTL_VFS_POINTER]
ae20: 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20   opcode finds a 
ae30: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74  pointer to the t
ae40: 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53  op-level.** [VFS
ae50: 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e  es] currently in
ae60: 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67   use.  ^(The arg
ae70: 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71  ument X in.** sq
ae80: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
ae90: 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e  ol(db,SQLITE_FCN
aea0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58  TL_VFS_POINTER,X
aeb0: 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20  ) must be.** of 
aec0: 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76  type "[sqlite3_v
aed0: 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f  fs] **".  This o
aee0: 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20  pcodes will set 
aef0: 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74  *X.** to a point
af00: 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65  er to the top-le
af10: 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57  vel VFS.)^.** ^W
af20: 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75  hen there are mu
af30: 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73  ltiple VFS shims
af40: 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74   in the stack, t
af50: 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  his opcode finds
af60: 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f   the.** upper-mo
af70: 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a  st shim only..**
af80: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
af90: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
afa0: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
afb0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
afc0: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
afd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
afe0: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
aff0: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
b000: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
b010: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
b020: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
b030: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
b040: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
b050: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
b060: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
b070: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
b080: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
b090: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
b0a0: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
b0b0: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
b0c0: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
b0d0: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
b0e0: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
b0f0: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
b100: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
b110: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
b120: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
b130: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
b140: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
b150: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
b160: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
b170: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
b180: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
b190: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
b1a0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b1b0: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
b1c0: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
b1d0: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
b1e0: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
b1f0: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
b200: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
b210: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
b220: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
b230: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
b240: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
b250: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
b260: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
b270: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
b280: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
b290: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
b2a0: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
b2b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b2c0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
b2d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
b2e0: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
b2f0: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
b300: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
b310: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
b320: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b330: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
b340: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
b350: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
b360: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
b370: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
b380: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
b390: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
b3a0: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
b3b0: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
b3c0: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
b3d0: 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73  statement if res
b3e0: 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55  ult string is NU
b3f0: 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75  LL, or that retu
b400: 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66  rns a copy.** of
b410: 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69   the result stri
b420: 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ng if the string
b430: 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a   is non-NULL..**
b440: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
b450: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
b460: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
b470: 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c  rns.** any resul
b480: 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61  t code other tha
b490: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  n [SQLITE_OK] or
b4a0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
b4b0: 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  D], that means.*
b4c0: 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65  * that the VFS e
b4d0: 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72  ncountered an er
b4e0: 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69  ror while handli
b4f0: 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20  ng the [PRAGMA] 
b500: 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  and the.** compi
b510: 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52  lation of the PR
b520: 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20  AGMA fails with 
b530: 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20  an error.  ^The 
b540: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b550: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
b560: 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20  ntrol occurs at 
b570: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
b580: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
b590: 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73  t analysis and s
b5a0: 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20  o.** it is able 
b5b0: 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c  to override buil
b5c0: 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74  t-in [PRAGMA] st
b5d0: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
b5e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b5f0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d  TL_BUSYHANDLER]]
b600: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
b610: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
b620: 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  ER].** file-cont
b630: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  rol may be invok
b640: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20  ed by SQLite on 
b650: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
b660: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72  e handle.** shor
b670: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20  tly after it is 
b680: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
b690: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73  to provide a cus
b6a0: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63  tom VFS with acc
b6b0: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  ess.** to the co
b6c0: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68  nnections busy-h
b6d0: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  andler callback.
b6e0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b6f0: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a   of type (void *
b700: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79  *).** - an array
b710: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29   of two (void *)
b720: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72   values. The fir
b730: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75  st (void *) actu
b740: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74  ally points.** t
b750: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
b760: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f  type (int (*)(vo
b770: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72  id *)). In order
b780: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63   to invoke the c
b790: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75  onnections.** bu
b7a0: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73  sy-handler, this
b7b0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
b7c0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
b7d0: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69   the second (voi
b7e0: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61  d *) in.** the a
b7f0: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79  rray as the only
b800: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74   argument. If it
b810: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
b820: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72  o, then the oper
b830: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
b840: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69  be retried. If i
b850: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  t returns zero, 
b860: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73  the custom VFS s
b870: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68  hould abandon th
b880: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65  e.** current ope
b890: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ration..**.** <l
b8a0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b8b0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a  _TEMPFILENAME]].
b8c0: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20  ** ^Application 
b8d0: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b  can invoke the [
b8e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
b8f0: 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d  PFILENAME] file-
b900: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61  control.** to ha
b910: 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61  ve SQLite genera
b920: 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  te a.** temporar
b930: 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67  y filename using
b940: 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
b950: 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c  thm that is foll
b960: 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65  owed to generate
b970: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
b980: 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50  lenames for TEMP
b990: 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65   tables and othe
b9a0: 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e  r internal uses.
b9b0: 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e    The.** argumen
b9c0: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68  t should be a ch
b9d0: 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  ar** which will 
b9e0: 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  be filled with t
b9f0: 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
ba00: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
ba10: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
ba20: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
ba30: 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72  ()].  The caller
ba40: 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b   should.** invok
ba50: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
ba60: 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74  )] on the result
ba70: 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f   to avoid a memo
ba80: 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c  ry leak..**.** <
ba90: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
baa0: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  L_MMAP_SIZE]].**
bab0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
bac0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
bad0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
bae0: 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73  ed to query or s
baf0: 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75  et the.** maximu
bb00: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
bb10: 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75  s that will be u
bb20: 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d  sed for memory-m
bb30: 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68  apped I/O..** Th
bb40: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
bb50: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
bb60: 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74  ue of type sqlit
bb70: 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a  e3_int64 that.**
bb80: 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20   is an advisory 
bb90: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
bba0: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  f bytes in the f
bbb0: 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61  ile to memory ma
bbc0: 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74  p.  The.** point
bbd0: 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  er is overwritte
bbe0: 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76  n with the old v
bbf0: 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74  alue.  The limit
bc00: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
bc10: 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  if.** the value 
bc20: 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74  originally point
bc30: 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76  ed to is negativ
bc40: 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75  e, and so the cu
bc50: 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20  rrent limit .** 
bc60: 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62  can be queried b
bc70: 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70  y passing in a p
bc80: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61  ointer to a nega
bc90: 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68  tive number.  Th
bca0: 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  is.** file-contr
bcb0: 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  ol is used inter
bcc0: 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65  nally to impleme
bcd0: 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  nt [PRAGMA mmap_
bce0: 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  size]..**.** <li
bcf0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bd00: 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  TRACE]].** The [
bd10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
bd20: 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  CE] file control
bd30: 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f   provides adviso
bd40: 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ry information.*
bd50: 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f  * to the VFS abo
bd60: 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68  ut what the high
bd70: 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65  er layers of the
bd80: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72   SQLite stack ar
bd90: 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73  e doing..** This
bda0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
bdb0: 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46   used by some VF
bdc0: 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69  S activity traci
bdd0: 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54  ng [shims]..** T
bde0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
bdf0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
be00: 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72   string.  Higher
be10: 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a   layers in the.*
be20: 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d  * SQLite stack m
be30: 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74  ay generate inst
be40: 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69  ances of this fi
be50: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a  le control if.**
be60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
be70: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f  _FCNTL_TRACE] co
be80: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
be90: 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
bea0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
beb0: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
bec0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
bed0: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
bee0: 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  D] file control 
bef0: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61  interprets its a
bf00: 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20  rgument as a.** 
bf10: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
bf20: 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69  teger and it wri
bf30: 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  tes a boolean in
bf40: 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
bf50: 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20  depending.** on 
bf60: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
bf70: 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e  he file has been
bf80: 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c   renamed, moved,
bf90: 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63   or deleted sinc
bfa0: 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73  e it.** was firs
bfb0: 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  t opened..**.** 
bfc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bfd0: 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e  TL_WIN32_GET_HAN
bfe0: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
bff0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c000: 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _GET_HANDLE] opc
c010: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
c020: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a  to obtain the.**
c030: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69   underlying nati
c040: 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61  ve file handle a
c050: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
c060: 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54   file handle.  T
c070: 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74  his file.** cont
c080: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69  rol interprets i
c090: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61  ts argument as a
c0a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61   pointer to a na
c0b0: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  tive file handle
c0c0: 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74   and.** writes t
c0d0: 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c  he resulting val
c0e0: 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ue there..**.** 
c0f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c100: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
c110: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
c120: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c130: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _SET_HANDLE] opc
c140: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
c150: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
c160: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
c170: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
c180: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61  ol method to swa
c190: 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c  p the file handl
c1a0: 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a  e with the one.*
c1b0: 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
c1c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
c1d0: 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c  t.  This capabil
c1e0: 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69  ity is used duri
c1f0: 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e  ng testing.** an
c200: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
c210: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
c220: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73  n SQLITE_TEST is
c230: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
c240: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c250: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a  TL_WAL_BLOCK]].*
c260: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c270: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69  NTL_WAL_BLOCK] i
c280: 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68  s a signal to th
c290: 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74  e VFS layer that
c2a0: 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20   it might.** be 
c2b0: 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20  advantageous to 
c2c0: 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78  block on the nex
c2d0: 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68  t WAL lock if th
c2e0: 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d  e lock is not im
c2f0: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61  mediately.** ava
c300: 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c  ilable.  The WAL
c310: 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65   subsystem issue
c320: 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75  s this signal du
c330: 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72  ring rare.** cir
c340: 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72  cumstances in or
c350: 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f  der to fix a pro
c360: 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69  blem with priori
c370: 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  ty inversion..**
c380: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
c390: 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d  ould <em>not</em
c3a0: 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d  > use this file-
c3b0: 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c  control..**.** <
c3c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c3d0: 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68  L_ZIPVFS]].** Th
c3e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c3f0: 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69  ZIPVFS] opcode i
c400: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
c410: 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c   zipvfs only. Al
c420: 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73  l other.** VFS s
c430: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c  hould return SQL
c440: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72  ITE_NOTFOUND for
c450: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a   this opcode..**
c460: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c470: 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20  _FCNTL_RBU]].** 
c480: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c490: 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73  L_RBU] opcode is
c4a0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
c4b0: 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
c4c0: 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52  used by.** the R
c4d0: 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c  BU extension onl
c4e0: 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46  y.  All other VF
c4f0: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
c500: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
c510: 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f  for.** this opco
c520: 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  de.  .**.** <li>
c530: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  [[SQLITE_FCNTL_B
c540: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
c550: 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53  E]].** If the [S
c560: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
c570: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
c580: 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73 20 53  opcode returns S
c590: 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a  QLITE_OK, then.*
c5a0: 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72  * the file descr
c5b0: 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65 64 20  iptor is placed 
c5c0: 69 6e 20 22 62 61 74 63 68 20 77 72 69 74 65 20  in "batch write 
c5d0: 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a 20  mode", which.** 
c5e0: 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73 65 71  means all subseq
c5f0: 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61  uent write opera
c600: 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64 65  tions will be de
c610: 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e 65 0a  ferred and done.
c620: 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61 74  ** atomically at
c630: 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c 49 54   the next [SQLIT
c640: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
c650: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20 53  TOMIC_WRITE].  S
c660: 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20 64  ystems.** that d
c670: 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 62 61  o not support ba
c680: 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69 74 65  tch atomic write
c690: 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  s will return SQ
c6a0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a  LITE_NOTFOUND..*
c6b0: 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 73  * ^Following a s
c6c0: 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49 54 45  uccessful SQLITE
c6d0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
c6e0: 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20 70 72  MIC_WRITE and pr
c6f0: 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6c  ior to.** the cl
c700: 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 43  osing [SQLITE_FC
c710: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
c720: 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b  C_WRITE] or.** [
c730: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c  SQLITE_FCNTL_ROL
c740: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49  LBACK_ATOMIC_WRI
c750: 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  TE], SQLite will
c760: 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53 20   make.** no VFS 
c770: 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 73 20  interface calls 
c780: 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c  on the same [sql
c790: 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65 20  ite3_file] file 
c7a0: 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65 78  descriptor.** ex
c7b0: 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73 20 74  cept for calls t
c7c0: 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d 65 74  o the xWrite met
c7d0: 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46 69 6c  hod and the xFil
c7e0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
c7f0: 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ** with [SQLITE_
c800: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
c810: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c820: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
c830: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d  T_ATOMIC_WRITE]]
c840: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c850: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c860: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64  MIC_WRITE] opcod
c870: 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69  e causes all wri
c880: 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73  te.** operations
c890: 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69   since the previ
c8a0: 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63  ous successful c
c8b0: 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49  all to .** [SQLI
c8c0: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c8d0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20  TOMIC_WRITE] to 
c8e0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61 74 6f  be performed ato
c8f0: 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73  mically..** This
c900: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
c910: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
c920: 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
c930: 20 74 68 65 20 77 72 69 74 65 73 20 77 65 72 65   the writes were
c940: 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d 65  .** all performe
c950: 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61  d successfully a
c960: 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63 6f 6d  nd have been com
c970: 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73 69 73  mitted to persis
c980: 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a 2a  tent storage..**
c990: 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
c9a0: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
c9b0: 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 2c  t is successful,
c9c0: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   this file contr
c9d0: 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65 20  ol takes.** the 
c9e0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20  file descriptor 
c9f0: 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69  out of batch wri
ca00: 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61 74 20  te mode so that 
ca10: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
ca20: 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  * write operatio
ca30: 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65  ns are independe
ca40: 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  nt..** ^SQLite w
ca50: 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
ca60: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
ca70: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
ca80: 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70  E without.** a p
ca90: 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
caa0: 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f  call to [SQLITE_
cab0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
cac0: 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a  IC_WRITE]..**.**
cad0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
cae0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
caf0: 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54  MIC_WRITE]].** T
cb00: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
cb10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
cb20: 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63  _WRITE] opcode c
cb30: 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a  auses all write.
cb40: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69  ** operations si
cb50: 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75 73  nce the previous
cb60: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
cb70: 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   to .** [SQLITE_
cb80: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
cb90: 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20  IC_WRITE] to be 
cba0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20  rolled back..** 
cbb0: 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72  ^This file contr
cbc0: 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66 69 6c  ol takes the fil
cbd0: 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74  e descriptor out
cbe0: 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65 20   of batch write 
cbf0: 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74 20  mode.** so that 
cc00: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77  all subsequent w
cc10: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
cc20: 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e  are independent.
cc30: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
cc40: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51   never invoke SQ
cc50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
cc60: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
cc70: 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72   without.** a pr
cc80: 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
cc90: 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46  all to [SQLITE_F
cca0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
ccb0: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20  C_WRITE]..**.** 
ccc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ccd0: 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 5d  TL_LOCK_TIMEOUT]
cce0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
ccf0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45  _FCNTL_LOCK_TIME
cd00: 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63 61 75 73  OUT] opcode caus
cd10: 65 73 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6f  es attempts to o
cd20: 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69 6c 65 20  btain.** a file 
cd30: 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68 65 20 78  lock using the x
cd40: 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c 6f 63 6b  Lock or xShmLock
cd50: 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20   methods of the 
cd60: 56 46 53 20 74 6f 20 77 61 69 74 0a 2a 2a 20 66  VFS to wait.** f
cd70: 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69 6c 6c 69  or up to M milli
cd80: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 66  seconds before f
cd90: 61 69 6c 69 6e 67 2c 20 77 68 65 72 65 20 4d 20  ailing, where M 
cda0: 69 73 20 74 68 65 20 73 69 6e 67 6c 65 20 0a 2a  is the single .*
cdb0: 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  * unsigned integ
cdc0: 65 72 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  er parameter..**
cdd0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </ul>.*/.#defin
cde0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
cdf0: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
ce00: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
ce10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45   SQLITE_FCNTL_GE
ce20: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
ce30: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
ce40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54  SQLITE_FCNTL_SET
ce50: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
ce60: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
ce70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
ce80: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
ce90: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
cea0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
ceb0: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  HINT            
cec0: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
ced0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
cee0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
cef0: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
cf00: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
cf10: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
cf20: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
cf30: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
cf40: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20  TTED            
cf50: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
cf60: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
cf70: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39  RETRY          9
cf80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cf90: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
cfa0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  L            10.
cfb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cfc0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20  CNTL_OVERWRITE  
cfd0: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
cfe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cff0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20  NTL_VFSNAME     
d000: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64             12.#d
d010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d020: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
d030: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65  RWRITE    13.#de
d040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d050: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  L_PRAGMA        
d060: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66           14.#def
d070: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d080: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20  _BUSYHANDLER    
d090: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69          15.#defi
d0a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d0b0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20  TEMPFILENAME    
d0c0: 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e         16.#defin
d0d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  e SQLITE_FCNTL_M
d0e0: 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20  MAP_SIZE        
d0f0: 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65        18.#define
d100: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52   SQLITE_FCNTL_TR
d110: 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ACE             
d120: 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20       19.#define 
d130: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
d140: 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20  _MOVED          
d150: 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53      20.#define S
d160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
d170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d180: 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51     21.#define SQ
d190: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
d1a0: 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20  T_PHASETWO      
d1b0: 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    22.#define SQL
d1c0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
d1d0: 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20  SET_HANDLE      
d1e0: 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   23.#define SQLI
d1f0: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
d200: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
d210: 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  24.#define SQLIT
d220: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20  E_FCNTL_ZIPVFS  
d230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
d240: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
d250: 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20  _FCNTL_RBU      
d260: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36                26
d270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d280: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
d290: 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a  R            27.
d2a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d2b0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
d2c0: 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 23  NTER        28.#
d2d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d2e0: 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41  NTL_WIN32_GET_HA
d2f0: 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64  NDLE       29.#d
d300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d310: 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20 20  TL_PDB          
d320: 20 20 20 20 20 20 20 20 20 20 33 30 0a 23 64 65            30.#de
d330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d340: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
d350: 52 49 54 45 20 20 20 20 20 33 31 0a 23 64 65 66  RITE     31.#def
d360: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d370: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57  _COMMIT_ATOMIC_W
d380: 52 49 54 45 20 20 20 20 33 32 0a 23 64 65 66 69  RITE    32.#defi
d390: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d3a0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
d3b0: 57 52 49 54 45 20 20 33 33 0a 23 64 65 66 69 6e  WRITE  33.#defin
d3c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
d3d0: 4f 43 4b 5f 54 49 4d 45 4f 55 54 20 20 20 20 20  OCK_TIMEOUT     
d3e0: 20 20 20 20 20 20 33 34 0a 0a 2f 2a 20 64 65 70        34../* dep
d3f0: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f  recated names */
d400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d410: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
d420: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
d430: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
d440: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
d450: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
d460: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
d470: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
d480: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
d490: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
d4a0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
d4b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
d4c0: 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a  ST_ERRNO.../*.**
d4d0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
d4e0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
d4f0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
d500: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
d510: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
d520: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
d530: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
d540: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
d550: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
d560: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
d570: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
d580: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
d590: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
d5a0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
d5b0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
d5c0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
d5d0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
d5e0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
d5f0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
d600: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
d610: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
d620: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
d630: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
d640: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
d650: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d660: 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73   Loadable Extens
d670: 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20  ion Thunk.**.** 
d680: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
d690: 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f   opaque sqlite3_
d6a0: 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72  api_routines str
d6b0: 75 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64  ucture is passed
d6c0: 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64   as.** the third
d6d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e   parameter to en
d6e0: 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c  try points of [l
d6f0: 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f  oadable extensio
d700: 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74  ns].  This.** st
d710: 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20  ructure must be 
d720: 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64  typedefed in ord
d730: 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  er to work aroun
d740: 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69  d compiler warni
d750: 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70  ngs.** on some p
d760: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70  latforms..*/.typ
d770: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d780: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
d790: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
d7a0: 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tines;../*.** CA
d7b0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
d7c0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
d7d0: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
d7e0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
d7f0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
d800: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
d810: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
d820: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
d830: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
d840: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
d850: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
d860: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
d870: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
d880: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
d890: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
d8a0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
d8b0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
d8c0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
d8d0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
d8e0: 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 69   VFS interface i
d8f0: 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 78 74 65  s sometimes exte
d900: 6e 64 65 64 20 62 79 20 61 64 64 69 6e 67 20 6e  nded by adding n
d910: 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a  ew methods onto.
d920: 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 45 61 63  ** the end.  Eac
d930: 68 20 74 69 6d 65 20 73 75 63 68 20 61 6e 20 65  h time such an e
d940: 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c  xtension occurs,
d950: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
d960: 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d  eld.** is increm
d970: 65 6e 74 65 64 2e 20 20 54 68 65 20 69 56 65 72  ented.  The iVer
d980: 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 61 72 74  sion value start
d990: 65 64 20 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a  ed out as 1 in.*
d9a0: 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f  * SQLite [versio
d9b0: 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74  n 3.5.0] on [dat
d9c0: 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e  eof:3.5.0], then
d9d0: 20 69 6e 63 72 65 61 73 65 64 20 74 6f 20 32 0a   increased to 2.
d9e0: 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b  ** with SQLite [
d9f0: 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f  version 3.7.0] o
da00: 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d  n [dateof:3.7.0]
da10: 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e 63 72 65  , and then incre
da20: 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74  ased.** to 3 wit
da30: 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f  h SQLite [versio
da40: 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74  n 3.7.6] on [dat
da50: 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64  eof:3.7.6].  Add
da60: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
da70: 2a 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  * may be appende
da80: 64 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  d to the sqlite3
da90: 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 6e 64 20  _vfs object and 
daa0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
dab0: 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61  ue.** may increa
dac0: 73 65 20 61 67 61 69 6e 20 69 6e 20 66 75 74 75  se again in futu
dad0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
dae0: 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  QLite..** Note t
daf0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
db00: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
db10: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
db20: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
db30: 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  ansition from.**
db40: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
db50: 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73   3.5.9] to [vers
db60: 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64  ion 3.6.0] on [d
db70: 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20  ateof:3.6.0].** 
db80: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
db90: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
dba0: 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ot modified..**.
dbb0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
dbc0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
dbd0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
dbe0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
dbf0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
dc00: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
dc10: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
dc20: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
dc30: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
dc40: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
dc50: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
dc60: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
dc70: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
dc80: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
dc90: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
dca0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
dcb0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
dcc0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
dcd0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
dce0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
dcf0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
dd00: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
dd10: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
dd20: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
dd30: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
dd40: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
dd50: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
dd60: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
dd70: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
dd80: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
dd90: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
dda0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
ddb0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
ddc0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
ddd0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
dde0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
ddf0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
de00: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
de10: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
de20: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
de30: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
de40: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
de50: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
de60: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
de70: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
de80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
de90: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
dea0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
deb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
dec0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
ded0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
dee0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
def0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
df00: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
df10: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
df20: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
df30: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
df40: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
df50: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
df60: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
df70: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
df80: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
df90: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
dfa0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
dfb0: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
dfc0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
dfd0: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
dfe0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
dff0: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
e000: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
e010: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
e020: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
e030: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
e040: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
e050: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
e060: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
e070: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
e080: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
e090: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
e0a0: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
e0b0: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
e0c0: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
e0d0: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
e0e0: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
e0f0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
e100: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
e110: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
e120: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
e130: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
e140: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
e150: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
e160: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
e170: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
e180: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
e190: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
e1a0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
e1b0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
e1c0: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
e1d0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e1e0: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
e1f0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
e200: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
e210: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
e220: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
e230: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
e240: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
e250: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
e260: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
e270: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
e280: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
e290: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
e2a0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
e2b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
e2c0: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
e2d0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
e2e0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
e2f0: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
e300: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
e310: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
e320: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
e330: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
e340: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
e350: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
e360: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
e370: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
e380: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
e390: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
e3a0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
e3b0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
e3c0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
e3d0: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
e3e0: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
e3f0: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
e400: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
e410: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
e420: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
e430: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
e440: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
e450: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
e460: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
e470: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
e480: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
e490: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
e4a0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
e4b0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
e4c0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
e4d0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e4e0: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
e4f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e500: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
e510: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e520: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
e530: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e540: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
e550: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
e560: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
e570: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
e580: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
e590: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
e5a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
e5b0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
e5c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e5d0: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
e5e0: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
e5f0: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
e600: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
e610: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
e620: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
e630: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
e640: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
e650: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
e660: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
e670: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
e680: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
e690: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
e6a0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
e6b0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
e6c0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
e6d0: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
e6e0: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
e6f0: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
e700: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
e710: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
e720: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
e730: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
e740: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
e750: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
e760: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
e770: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
e780: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
e790: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
e7a0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
e7b0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
e7c0: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
e7d0: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
e7e0: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
e7f0: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
e800: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
e810: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
e820: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
e830: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
e840: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
e850: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
e860: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
e870: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
e880: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
e890: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
e8a0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
e8b0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
e8c0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
e8d0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
e8e0: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
e8f0: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
e900: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
e910: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
e920: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
e930: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
e940: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
e950: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
e960: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
e970: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
e980: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
e990: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
e9a0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
e9b0: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
e9c0: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
e9d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
e9e0: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
e9f0: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
ea00: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
ea10: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
ea20: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
ea30: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
ea40: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
ea50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
ea60: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
ea70: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
ea80: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
ea90: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
eaa0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
eab0: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
eac0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
ead0: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
eae0: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
eaf0: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
eb00: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
eb10: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
eb20: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
eb30: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
eb40: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
eb50: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
eb60: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
eb70: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
eb80: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
eb90: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
eba0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
ebb0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
ebc0: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
ebd0: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
ebe0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
ebf0: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
ec00: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
ec10: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
ec20: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
ec30: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
ec40: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
ec50: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
ec60: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
ec70: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
ec80: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
ec90: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
eca0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
ecb0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
ecc0: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
ecd0: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
ece0: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
ecf0: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
ed00: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
ed10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
ed20: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
ed30: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
ed40: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
ed50: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
ed60: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
ed70: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
ed80: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
ed90: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
eda0: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
edb0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
edc0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
edd0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
ede0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
edf0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
ee00: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
ee10: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
ee20: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
ee30: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
ee40: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
ee50: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
ee60: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
ee70: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
ee80: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
ee90: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
eea0: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
eeb0: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
eec0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
eed0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
eee0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
eef0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
ef00: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
ef10: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
ef20: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
ef30: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
ef40: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
ef50: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
ef60: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
ef70: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
ef80: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
ef90: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
efa0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
efb0: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
efc0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
efd0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
efe0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
eff0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
f000: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
f010: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
f020: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
f030: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
f040: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
f050: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
f060: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
f070: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
f080: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
f090: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
f0a0: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
f0b0: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
f0c0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
f0d0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
f0e0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
f0f0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
f100: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
f110: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
f120: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
f130: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
f140: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
f150: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
f160: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
f170: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
f180: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
f190: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
f1a0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
f1b0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
f1c0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
f1d0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
f1e0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
f1f0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
f200: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
f210: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
f220: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
f230: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
f240: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
f250: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
f260: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
f270: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
f280: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
f290: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
f2a0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
f2b0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
f2c0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
f2d0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
f2e0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
f2f0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
f300: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
f310: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
f320: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
f330: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
f340: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
f350: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
f360: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
f370: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
f380: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
f390: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
f3a0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
f3b0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
f3c0: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
f3d0: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
f3e0: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
f3f0: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
f400: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
f410: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
f420: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
f430: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
f440: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
f450: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
f460: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
f470: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
f480: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
f490: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
f4a0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
f4b0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
f4c0: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
f4d0: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
f4e0: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
f4f0: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
f500: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
f510: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
f520: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
f530: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
f540: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
f550: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
f560: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
f570: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
f580: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
f590: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
f5a0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
f5b0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
f5c0: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
f5d0: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
f5e0: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
f5f0: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
f600: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
f610: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
f620: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
f630: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
f640: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
f650: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
f660: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
f670: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
f680: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
f690: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
f6a0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
f6b0: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
f6c0: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
f6d0: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
f6e0: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
f6f0: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
f700: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
f710: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
f720: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
f730: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
f740: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
f750: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
f760: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
f770: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
f780: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
f790: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
f7a0: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
f7b0: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
f7c0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
f7d0: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
f7e0: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
f7f0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
f800: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
f810: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
f820: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
f830: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
f840: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
f850: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
f860: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
f870: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
f880: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
f890: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
f8a0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
f8b0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
f8c0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
f8d0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
f8e0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
f8f0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
f900: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
f910: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
f920: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
f930: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
f940: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
f950: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
f960: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
f970: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
f980: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
f990: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
f9a0: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
f9b0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
f9c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
f9d0: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
f9e0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
f9f0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
fa00: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
fa10: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
fa20: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fa30: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
fa40: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
fa50: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
fa60: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fa70: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
fa80: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
fa90: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
faa0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
fab0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
fac0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
fad0: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
fae0: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
faf0: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
fb00: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
fb10: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
fb20: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
fb30: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
fb40: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
fb50: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
fb60: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
fb70: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
fb80: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
fb90: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
fba0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
fbb0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
fbc0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
fbd0: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
fbe0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
fbf0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
fc00: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
fc10: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
fc20: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
fc30: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
fc40: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
fc50: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
fc60: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
fc70: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
fc80: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
fc90: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
fca0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
fcb0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
fcc0: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
fcd0: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
fce0: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
fcf0: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
fd00: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
fd10: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
fd20: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
fd30: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
fd40: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
fd50: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
fd60: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
fd70: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
fd80: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
fd90: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
fda0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
fdb0: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
fdc0: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
fdd0: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
fde0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
fdf0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
fe00: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
fe10: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
fe20: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
fe30: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
fe40: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
fe50: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
fe60: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
fe70: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
fe80: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
fe90: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
fea0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
feb0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
fec0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
fed0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
fee0: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
fef0: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
ff00: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
ff10: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
ff20: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
ff30: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
ff40: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
ff50: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
ff60: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
ff70: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
ff80: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
ff90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
ffa0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
ffb0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
ffc0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
ffd0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
ffe0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
fff0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
10000 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
10010 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
10020 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
10030 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
10040 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
10050 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
10060 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10070 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
10080 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
10090 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
100a0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
100b0 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
100c0 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
100d0 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
100e0 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
100f0 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
10100 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10110 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
10120 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
10130 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
10140 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
10150 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
10160 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
10170 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
10180 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
10190 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
101a0 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
101b0 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
101c0 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
101d0 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
101e0 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
101f0 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
10200 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
10210 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
10220 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
10230 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
10240 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
10250 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
10260 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
10270 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10280 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
10290 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
102a0 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
102b0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
102c0 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
102d0 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
102e0 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
102f0 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
10300 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
10310 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
10320 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
10330 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
10340 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
10350 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10360 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
10370 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
10380 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
10390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
103a0 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
103b0 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
103c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
103d0 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
103e0 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
103f0 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
10400 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
10410 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
10420 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
10430 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
10440 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
10450 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
10460 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
10470 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
10480 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
10490 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
104a0 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
104b0 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
104c0 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
104d0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
104e0 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
104f0 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
10500 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10510 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
10520 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
10530 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10540 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
10550 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
10560 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10570 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
10580 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
10590 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
105a0 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
105b0 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
105c0 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
105d0 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
105e0 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
105f0 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65  ven on the corre
10600 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
10610 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
10620 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
10630 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
10640 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
10650 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
10660 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
10670 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
10680 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
10690 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
106a0 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
106b0 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
106c0 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
106d0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
106e0 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
106f0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
10700 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
10710 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
10720 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
10730 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
10740 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
10750 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
10760 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
10770 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
10780 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
10790 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
107a0 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
107b0 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
107c0 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
107d0 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
107e0 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
107f0 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
10800 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
10810 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
10820 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
10830 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
10840 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10850 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
10860 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
10870 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
10880 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
10890 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
108a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
108b0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
108c0 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
108d0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
108e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
108f0 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
10900 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
10910 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
10920 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
10930 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
10940 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
10950 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
10960 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
10970 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
10980 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
10990 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
109a0 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
109b0 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
109c0 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
109d0 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
109e0 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
109f0 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
10a00 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
10a10 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
10a20 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
10a30 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
10a40 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
10a50 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
10a60 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
10a70 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
10a80 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
10a90 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
10aa0 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
10ab0 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
10ac0 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
10ad0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10ae0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
10af0 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
10b00 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
10b10 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
10b20 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
10b30 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
10b40 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
10b50 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
10b60 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
10b70 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
10b80 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
10b90 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
10ba0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10bb0 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
10bc0 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
10bd0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
10be0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
10bf0 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
10c00 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
10c10 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
10c20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
10c30 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
10c40 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10c50 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
10c60 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
10c70 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
10c80 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
10c90 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
10ca0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
10cb0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
10cc0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10cd0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
10ce0 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
10cf0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10d00 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
10d10 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
10d20 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
10d30 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
10d40 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
10d50 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
10d60 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
10d70 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
10d80 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
10d90 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
10da0 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
10db0 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
10dc0 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
10dd0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
10de0 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
10df0 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
10e00 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
10e10 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
10e20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
10e30 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
10e40 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
10e50 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
10e60 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
10e70 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
10e80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
10e90 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
10ea0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
10eb0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
10ec0 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
10ed0 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
10ee0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10ef0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
10f00 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
10f10 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
10f20 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
10f30 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
10f40 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
10f50 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
10f60 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
10f70 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
10f80 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
10f90 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
10fa0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10fb0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
10fc0 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
10fd0 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
10fe0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
10ff0 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
11000 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
11010 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
11020 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
11030 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11040 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
11050 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
11060 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
11070 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
11080 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
11090 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
110a0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
110b0 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
110c0 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
110d0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
110e0 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
110f0 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
11100 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
11110 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
11120 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11130 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
11140 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
11150 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
11160 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
11170 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
11180 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
11190 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
111a0 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
111b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
111c0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
111d0 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
111e0 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
111f0 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
11200 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11210 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
11220 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
11230 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
11240 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
11250 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
11260 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11270 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
11280 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
11290 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
112a0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
112b0 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
112c0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
112d0 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
112e0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
112f0 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
11300 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
11310 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11320 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
11330 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
11340 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
11350 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
11360 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
11370 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
11380 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
11390 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
113a0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
113b0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
113c0 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
113d0 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
113e0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
113f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
11400 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
11410 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
11420 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
11430 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
11440 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
11450 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
11460 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
11470 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
11480 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
11490 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
114a0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
114b0 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
114c0 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
114d0 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
114e0 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
114f0 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
11500 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
11510 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
11520 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
11530 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
11540 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
11550 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
11560 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
11570 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
11580 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
11590 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
115a0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
115b0 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
115c0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
115d0 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
115e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
115f0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
11600 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
11610 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
11620 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
11630 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11640 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
11650 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
11660 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
11670 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
11680 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
11690 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
116a0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
116b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
116c0 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
116d0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
116e0 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
116f0 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
11700 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
11710 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
11720 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
11730 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
11740 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
11750 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
11760 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
11770 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
11780 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
11790 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
117a0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
117b0 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
117c0 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
117d0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
117e0 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
117f0 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
11800 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
11810 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11820 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
11830 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
11840 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
11850 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
11860 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
11870 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
11880 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
11890 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
118a0 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
118b0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
118c0 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
118d0 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
118e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
118f0 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
11900 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
11910 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
11920 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
11930 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
11940 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
11950 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
11960 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
11970 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
11980 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
11990 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
119a0 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
119b0 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
119c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
119d0 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
119e0 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
119f0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
11a00 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
11a10 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
11a20 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
11a30 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
11a40 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
11a50 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
11a60 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
11a70 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
11a80 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65  ds..**.** <b>The
11a90 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11aa0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
11ab0 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54  ot threadsafe. T
11ac0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
11ad0 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68  * must ensure th
11ae0 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
11af0 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
11b00 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
11b10 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
11b20 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
11b30 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
11b40 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  </b>.**.** The s
11b50 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11b60 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79  interface.** may
11b70 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
11b80 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
11b90 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
11ba0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
11bb0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
11bc0 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
11bd0 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
11be0 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
11bf0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
11c00 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
11c10 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
11c20 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
11c30 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
11c40 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
11c50 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
11c60 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
11c70 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
11c80 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
11c90 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
11ca0 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
11cb0 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
11cc0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
11cd0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
11ce0 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
11cf0 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
11d00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11d10 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
11d20 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
11d30 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
11d40 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
11d50 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
11d60 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
11d70 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
11d80 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
11d90 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
11da0 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
11db0 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
11dc0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11dd0 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
11de0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
11df0 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
11e00 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11e10 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
11e20 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
11e30 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
11e40 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
11e50 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
11e60 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
11e70 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
11e80 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
11e90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
11ea0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
11eb0 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  code]..*/.int sq
11ec0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
11ed0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
11ee0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
11ef0 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
11f00 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  ections.** METHO
11f10 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
11f20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
11f30 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
11f40 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
11f50 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
11f60 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
11f70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11f80 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
11f90 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
11fa0 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
11fb0 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
11fc0 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
11fd0 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
11fe0 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
11ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
12000 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
12010 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
12020 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
12030 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
12040 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
12050 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65  D,V,...)  is the
12060 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  .** [SQLITE_DBCO
12070 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c  NFIG_LOOKASIDE |
12080 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
12090 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65  erb] - an intege
120a0 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20  r code .** that 
120b0 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61  indicates what a
120c0 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
120d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
120e0 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
120f0 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65  igured..** Subse
12100 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20  quent arguments 
12110 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
12120 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
12130 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  ion verb..**.** 
12140 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
12150 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
12160 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
12170 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
12180 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
12190 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
121a0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
121b0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
121c0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
121d0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
121e0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
121f0 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
12200 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
12210 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12220 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
12230 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
12240 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
12250 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
12260 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
12270 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
12280 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
12290 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
122a0 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
122b0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
122c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
122d0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
122e0 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
122f0 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
12300 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
12310 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
12320 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
12330 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12340 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
12350 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
12360 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
12370 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
12380 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12390 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
123a0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
123b0 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
123c0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
123d0 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
123e0 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
123f0 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
12400 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
12410 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
12420 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
12430 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
12440 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
12450 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
12460 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
12470 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
12480 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
12490 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
124a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
124b0 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
124c0 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
124d0 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
124e0 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
124f0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
12500 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
12510 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
12520 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
12530 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
12540 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
12550 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
12560 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12570 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
12580 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
12590 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
125a0 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
125b0 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
125c0 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
125d0 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
125e0 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
125f0 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
12600 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
12610 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
12620 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
12630 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
12640 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
12650 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
12660 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
12670 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61  he xMalloc, xRea
12680 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20  lloc, and xFree 
12690 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
126a0 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
126b0 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
126c0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
126d0 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
126e0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
126f0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  ry..** ^SQLite g
12700 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
12710 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
12720 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
12730 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
12740 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
12750 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
12760 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20  xRoundup..**.** 
12770 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
12780 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
12790 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
127a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
127b0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
127c0 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
127d0 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
127e0 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
127f0 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
12800 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
12810 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
12820 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
12830 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
12840 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
12850 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
12860 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
12870 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
12880 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
12890 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
128a0 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
128b0 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
128c0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
128d0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
128e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
128f0 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
12900 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
12910 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
12920 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
12930 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
12940 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
12950 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
12960 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
12970 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
12980 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
12990 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
129a0 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
129b0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
129c0 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
129d0 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
129e0 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
129f0 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
12a00 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
12a10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
12a20 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
12a30 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
12a40 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
12a50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
12a60 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a   For example,.**
12a70 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
12a80 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
12a90 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
12aa0 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
12ab0 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
12ac0 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
12ad0 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
12ae0 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
12af0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
12b00 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
12b10 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
12b20 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
12b30 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
12b40 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
12b50 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
12b60 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
12b70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
12b80 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
12b90 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
12ba0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
12bb0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
12bc0 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
12bd0 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
12be0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
12bf0 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
12c00 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
12c10 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
12c20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
12c30 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
12c40 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
12c50 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
12c60 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
12c70 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
12c80 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
12c90 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
12ca0 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
12cb0 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
12cc0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
12cd0 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
12ce0 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
12cf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12d00 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
12d10 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
12d20 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
12d30 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
12d40 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
12d50 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
12d60 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
12d70 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
12d80 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
12d90 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
12da0 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
12db0 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
12dc0 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
12dd0 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
12de0 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
12df0 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
12e00 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
12e10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
12e20 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
12e30 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
12e40 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
12e50 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
12e60 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
12e70 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
12e80 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
12e90 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
12ea0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12eb0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
12ec0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
12ed0 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
12ee0 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
12ef0 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
12f00 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
12f10 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
12f20 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
12f30 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
12f40 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
12f50 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
12f60 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
12f70 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
12f80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
12f90 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
12fa0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
12fb0 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
12fc0 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
12fd0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
12fe0 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
12ff0 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
13000 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
13010 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
13020 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
13030 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
13040 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
13050 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
13060 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
13070 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
13080 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
13090 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
130a0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
130b0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
130c0 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
130d0 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
130e0 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
130f0 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
13100 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
13110 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
13120 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
13130 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
13140 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
13150 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
13160 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
13170 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
13180 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13190 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
131a0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
131b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
131c0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
131d0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
131e0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
131f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13200 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
13210 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
13220 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
13230 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
13240 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13250 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
13260 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
13270 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
13280 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
13290 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
132a0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
132b0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
132c0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
132d0 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
132e0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
132f0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
13300 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
13310 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
13320 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
13330 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
13340 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13350 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
13360 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
13370 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13380 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
13390 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
133a0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
133b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
133c0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
133d0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
133e0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
133f0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
13400 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
13410 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
13420 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
13430 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
13440 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
13450 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
13460 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
13470 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
13480 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
13490 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
134a0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
134b0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
134c0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
134d0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
134e0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
134f0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
13500 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
13510 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
13520 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
13530 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
13540 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
13550 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
13560 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
13570 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
13580 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
13590 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
135a0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
135b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
135c0 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
135d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
135e0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
135f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13600 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
13610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13620 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
13630 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
13640 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
13650 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
13660 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
13670 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
13680 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
13690 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
136a0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
136b0 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
136c0 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
136d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
136e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
136f0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
13700 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
13710 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
13720 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
13730 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
13740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13750 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
13760 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
13770 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
13780 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
13790 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
137a0 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
137b0 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
137c0 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
137d0 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
137e0 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
137f0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
13800 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
13810 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13820 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
13830 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
13840 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13850 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
13860 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
13870 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
13880 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
13890 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
138a0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
138b0 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
138c0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
138d0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
138e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
138f0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
13900 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
13910 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
13920 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
13930 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
13940 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13950 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
13960 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13970 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
13980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
13990 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
139a0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
139b0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
139c0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
139d0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
139e0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
139f0 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
13a00 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
13a10 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
13a20 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
13a30 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
13a40 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
13a50 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
13a60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13a70 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
13a80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
13a90 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
13aa0 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
13ab0 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
13ac0 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
13ad0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
13ae0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13af0 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
13b00 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
13b10 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
13b20 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
13b30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
13b40 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
13b50 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
13b60 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
13b70 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
13b80 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
13b90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13ba0 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
13bb0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
13bc0 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
13bd0 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
13be0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
13bf0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
13c00 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
13c10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
13c20 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
13c30 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
13c40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13c50 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
13c60 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
13c70 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
13c80 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
13c90 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
13ca0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13cb0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
13cc0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
13cd0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
13ce0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
13cf0 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
13d00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
13d10 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13d20 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
13d30 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13d40 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
13d50 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
13d70 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
13d80 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13d90 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
13da0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13db0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
13dc0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
13dd0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13de0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
13df0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
13e00 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
13e10 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
13e20 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
13e30 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
13e40 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
13e50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
13e60 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
13e70 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
13e80 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
13e90 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
13ea0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
13eb0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
13ec0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
13ed0 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
13ee0 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
13ef0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
13f00 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
13f10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13f20 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
13f30 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13f40 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
13f50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
13f60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13f70 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
13f80 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13f90 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
13fa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13fb0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13fc0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
13fd0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13fe0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
13ff0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
14000 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
14010 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
14020 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
14030 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14040 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
14050 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
14060 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
14070 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
14080 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
14090 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
140a0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
140b0 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
140c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
140d0 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
140e0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
140f0 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
14100 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
14110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
14120 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  ALL_MALLOC]] <dt
14130 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
14140 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  MALL_MALLOC</dt>
14150 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
14160 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c  LITE_CONFIG_SMAL
14170 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  L_MALLOC option 
14180 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
14190 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65  ument of.** type
141a0 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65   int, interprete
141b0 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20  d as a boolean, 
141c0 77 68 69 63 68 20 69 66 20 74 72 75 65 20 70 72  which if true pr
141d0 6f 76 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f  ovides a hint to
141e0 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20  .** SQLite that 
141f0 69 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20  it should avoid 
14200 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  large memory all
14210 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73  ocations if poss
14220 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ible..** SQLite 
14230 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20  will run faster 
14240 69 66 20 69 74 20 69 73 20 66 72 65 65 20 74 6f  if it is free to
14250 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f   make large memo
14260 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a  ry allocations,.
14270 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c  ** but some appl
14280 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72  ication might pr
14290 65 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77  efer to run slow
142a0 65 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66  er in exchange f
142b0 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  or.** guarantees
142c0 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72   about memory fr
142d0 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  agmentation that
142e0 20 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66   are possible if
142f0 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61   large.** alloca
14300 74 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65  tions are avoide
14310 64 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  d.  This hint is
14320 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a   normally off..*
14330 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
14340 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14350 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
14360 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
14370 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
14380 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
14390 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
143a0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
143b0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
143c0 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74  type int,.** int
143d0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
143e0 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
143f0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
14400 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
14410 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  of.** memory all
14420 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
14430 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
14440 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
14450 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64  tistics are.** d
14460 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
14470 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
14480 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
14490 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
144a0 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
144b0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
144c0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
144d0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
144e0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
144f0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
14500 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
14510 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
14520 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
14530 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20  tatus64()].**   
14540 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
14550 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
14560 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
14570 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
14580 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
14590 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
145a0 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
145b0 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
145c0 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
145d0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
145e0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
145f0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
14600 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
14610 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14620 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c  NFIG_SCRATCH]] <
14630 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14640 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
14650 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
14660 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
14670 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e  option is no lon
14680 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64  ger used..** </d
14690 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
146a0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
146b0 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
146c0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
146d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
146e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
146f0 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f  _PAGECACHE optio
14700 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65  n specifies a me
14710 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61  mory pool.** tha
14720 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
14730 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
14740 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
14750 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
14760 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
14770 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
14780 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
14790 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20  ion option is a 
147a0 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c  no-op if an appl
147b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
147c0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
147d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
147e0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
147f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
14800 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65  CACHE2]..** ^The
14810 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
14820 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
14830 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14840 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
14850 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
14860 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c  d memory (pMem),
14870 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
14880 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e  h page cache lin
14890 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  e (sz),.** and t
148a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63  he number of cac
148b0 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a  he lines (N)..**
148c0 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
148d0 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
148e0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
148f0 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
14900 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
14910 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
14920 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20  and 65536) plus 
14930 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73  some extra bytes
14940 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
14950 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
14960 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20  number of extra 
14970 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20  bytes needed by 
14980 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a  the page header.
14990 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
149a0 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49  ined using [SQLI
149b0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
149c0 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20  _HDRSZ]..** ^It 
149d0 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
149e0 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
149f0 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f  ed memory,.** fo
14a00 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74  r the sz paramet
14a10 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20  er to be larger 
14a20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20  than necessary. 
14a30 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67   The pMem.** arg
14a40 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69  ument must be ei
14a50 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
14a60 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ter or a pointer
14a70 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
14a80 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f   aligned block o
14a90 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c  f memory of at l
14aa0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c  east sz*N bytes,
14ab0 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75   otherwise.** su
14ac0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
14ad0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
14ae0 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73  ** ^When pMem is
14af0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
14b00 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f  e will strive to
14b10 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
14b20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73  provided.** to s
14b30 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68  atisfy page cach
14b40 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67  e needs, falling
14b50 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65   back to [sqlite
14b60 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a  3_malloc()] if.*
14b70 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c  * a page cache l
14b80 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68  ine is larger th
14b90 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69  an sz bytes or i
14ba0 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65  f all of the pMe
14bb0 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65  m buffer.** is e
14bc0 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66  xhausted..** ^If
14bd0 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e   pMem is NULL an
14be0 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  d N is non-zero,
14bf0 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62   then each datab
14c00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
14c10 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61  * does an initia
14c20 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f  l bulk allocatio
14c30 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  n for page cache
14c40 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20   memory.** from 
14c50 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14c60 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f  )] sufficient fo
14c70 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20  r N cache lines 
14c80 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  if N is positive
14c90 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a   or.** of -1024*
14ca0 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20  N bytes if N is 
14cb0 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20  negative, . ^If 
14cc0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
14cd0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
14ce0 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
14cf0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
14d00 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c  d by the initial
14d10 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  .** allocation, 
14d20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73  then SQLite goes
14d30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
14d40 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c  loc()] separatel
14d50 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64  y for each.** ad
14d60 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c  ditional cache l
14d70 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ine. </dd>.**.**
14d80 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14d90 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
14da0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
14db0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
14dc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14dd0 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  EAP option speci
14de0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
14df0 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20  mory buffer .** 
14e00 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
14e10 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
14e20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
14e30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14e40 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68  eds.** beyond th
14e50 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72  ose provided for
14e60 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
14e70 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
14e80 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  * ^The SQLITE_CO
14e90 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
14ea0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
14eb0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
14ec0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
14ed0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
14ee0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
14ef0 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  or [SQLITE_ENABL
14f00 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72  E_MEMSYS5] and r
14f10 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
14f20 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f  E_ERROR] if invo
14f30 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ked otherwise..*
14f40 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
14f50 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
14f60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14f70 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65  AP:.** An 8-byte
14f80 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
14f90 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
14fa0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
14fb0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
14fc0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
14fd0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
14fe0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
14ff0 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
15000 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
15010 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
15020 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
15030 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
15040 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
15050 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
15060 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
15070 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
15080 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
15090 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
150a0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
150b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
150c0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
150d0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
150e0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74   not NULL then t
150f0 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
15100 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
15110 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
15120 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
15130 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
15140 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
15150 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
15160 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
15170 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
15180 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
15190 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
151a0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
151b0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
151c0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
151d0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
151e0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
151f0 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
15200 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
15210 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
15220 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
15230 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
15240 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
15250 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
15260 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15270 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
15280 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
15290 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
152a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
152b0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  G_MUTEX option t
152c0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
152d0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
152e0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
152f0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
15300 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
15310 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
15320 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
15330 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  ument specifies 
15340 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
15350 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
15360 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a  ines to be used.
15370 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20  ** in place the 
15380 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
15390 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
153a0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
153b0 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  es a copy of.** 
153c0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
153d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
153e0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
153f0 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
15400 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
15410 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
15420 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
15430 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
15440 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
15450 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
15460 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
15470 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
15480 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
15490 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
154a0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
154b0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
154c0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
154d0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
154e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
154f0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
15500 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
15510 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15520 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
15530 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
15540 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
15550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15560 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
15570 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
15580 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
15590 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
155a0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74  FIG_GETMUTEX opt
155b0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
155c0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
155d0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
155e0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
155f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
15600 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
15610 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
15620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
15630 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
15640 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
15650 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
15660 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
15670 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
15680 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
15690 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
156a0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
156b0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
156c0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
156d0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
156e0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
156f0 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
15700 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
15710 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
15720 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
15730 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
15740 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
15750 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
15760 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
15770 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
15780 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15790 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
157a0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
157b0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
157c0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
157d0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
157e0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
157f0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
15800 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15810 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
15820 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
15830 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
15840 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
15850 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15860 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
15870 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
15880 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15890 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
158a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
158b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69  G_LOOKASIDE opti
158c0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
158d0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
158e0 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66  rmine.** the def
158f0 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f  ault size of loo
15900 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e  kaside memory on
15910 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20   each [database 
15920 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
15930 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15940 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
15950 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
15960 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
15970 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
15980 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
15990 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
159a0 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
159b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
159c0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46  ^  ^(SQLITE_CONF
159d0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20  IG_LOOKASIDE.** 
159e0 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61  sets the <i>defa
159f0 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
15a00 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
15a10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15a20 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f  KASIDE].** optio
15a30 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  n to [sqlite3_db
15a40 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
15a50 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
15a60 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
15a70 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
15a80 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
15a90 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
15aa0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15ab0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
15ac0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15ad0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
15ae0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
15af0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15b00 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
15b10 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15b20 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
15b30 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
15b40 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
15b50 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
15b60 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
15b70 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
15b80 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61  e interface to a
15b90 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
15ba0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
15bb0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  n.)^.** ^SQLite 
15bc0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
15bd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  the [sqlite3_pca
15be0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
15bf0 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ject.</dd>.**.**
15c00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15c10 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
15c20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15c30 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
15c40 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
15c50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15c60 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
15c70 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15c80 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
15c90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15ca0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
15cb0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
15cc0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
15cd0 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72  es of.** the cur
15ce0 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20  rent page cache 
15cf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
15d00 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
15d10 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
15d20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
15d30 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
15d40 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
15d50 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
15d60 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
15d70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
15d80 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
15d90 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
15da0 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
15db0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15dc0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
15dd0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
15de0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
15df0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
15e00 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
15e10 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
15e20 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
15e30 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
15e40 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
15e50 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
15e60 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
15e70 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
15e80 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
15e90 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
15ea0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
15eb0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
15ec0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
15ed0 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
15ee0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
15ef0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
15f00 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
15f10 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
15f20 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
15f30 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15f40 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
15f50 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
15f60 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
15f70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15f80 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
15f90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
15fa0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
15fb0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
15fc0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
15fd0 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
15fe0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
15ff0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
16000 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
16010 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
16020 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
16030 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
16040 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
16050 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
16060 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
16070 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
16080 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
16090 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
160a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
160b0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
160c0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
160d0 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
160e0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
160f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
16100 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
16110 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
16120 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
16130 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
16140 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
16150 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
16160 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
16170 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
16180 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
16190 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
161a0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
161b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
161c0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
161d0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
161e0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
161f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16200 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
16210 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16220 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
16230 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16240 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b  G_URI option tak
16250 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
16260 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
16270 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  ..** If non-zero
16280 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
16290 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
162a0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
162b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
162c0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68  o,.** then URI h
162d0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
162e0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20  lly disabled.)^ 
162f0 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  ^If URI handling
16300 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
16310 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
16320 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f  enames passed to
16330 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
16340 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
16350 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
16360 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
16370 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
16380 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
16390 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
163a0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
163b0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
163c0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
163d0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
163e0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
163f0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
16400 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
16410 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
16420 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61   ^If it is globa
16430 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
16440 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
16450 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
16460 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
16470 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
16480 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
16490 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
164a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
164b0 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75  ened. ^(By defau
164c0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
164d0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
164e0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
164f0 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
16500 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
16510 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
16520 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
16530 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
16540 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ned.)^.**.** [[S
16550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
16560 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
16570 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16580 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
16590 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
165a0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
165b0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
165c0 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61  X_SCAN option ta
165d0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
165e0 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  eger.** argument
165f0 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
16600 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
16610 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
16620 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
16630 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63  .** the use of c
16640 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
16650 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
16660 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
16670 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20  y optimizer..** 
16680 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
16690 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e  ting is determin
166a0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51  ed.** by the [SQ
166b0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52  LITE_ALLOW_COVER
166c0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20  ING_INDEX_SCAN] 
166d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
166e0 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a  ion, or is "on".
166f0 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69  ** if that compi
16700 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
16710 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68  s omitted..** Th
16720 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73  e ability to dis
16730 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
16740 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
16750 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
16760 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61  scans.** is beca
16770 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65  use some incorre
16780 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63  ctly coded legac
16790 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  y applications m
167a0 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e  ight malfunction
167b0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74  .** when the opt
167c0 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61  imization is ena
167d0 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67  bled.  Providing
167e0 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a   the ability to.
167f0 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f  ** disable the o
16800 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f  ptimization allo
16810 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75  ws the older, bu
16820 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ggy application 
16830 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  code to work.** 
16840 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65  without change e
16850 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76  ven with newer v
16860 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
16870 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
16880 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
16890 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ] [[SQLITE_CONFI
168a0 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a  G_GETPCACHE]].**
168b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
168c0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51  IG_PCACHE and SQ
168d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
168e0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68  CACHE.** <dd> Th
168f0 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20  ese options are 
16900 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f  obsolete and sho
16910 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
16920 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20  by new code..** 
16930 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65  They are retaine
16940 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
16950 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75  compatibility bu
16960 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73  t are now no-ops
16970 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
16980 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16990 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74  _SQLLOG]].** <dt
169a0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
169b0 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69  QLLOG.** <dd>Thi
169c0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
169d0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71   available if sq
169e0 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  lite is compiled
169f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
16a00 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c  LITE_ENABLE_SQLL
16a10 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OG] pre-processo
16a20 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
16a30 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16a40 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  ent should.** be
16a50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
16a60 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
16a70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
16a80 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68  qlite3*,const ch
16a90 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68  ar*, int)..** Th
16aa0 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20  e second should 
16ab0 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  be of type (void
16ac0 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  *). The callback
16ad0 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74   is invoked by t
16ae0 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e  he library.** in
16af0 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20   three separate 
16b00 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69  circumstances, i
16b10 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
16b20 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
16b30 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
16b40 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65  arameter. If the
16b50 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
16b60 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65  r is 0, then the
16b70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16b80 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61  tion.** passed a
16b90 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
16ba0 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62  ument has just b
16bb0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20  een opened. The 
16bc0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
16bd0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75  * points to a bu
16be0 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ffer containing 
16bf0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
16c00 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
16c10 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  le. If the.** fo
16c20 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
16c30 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51  s 1, then the SQ
16c40 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
16c50 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
16c60 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  eter.** points t
16c70 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  o has just been 
16c80 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66  executed. Or, if
16c90 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
16ca0 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e  meter is 2, then
16cb0 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  .** the connecti
16cc0 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20  on being passed 
16cd0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
16ce0 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67  rameter is being
16cf0 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20   closed. The.** 
16d00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16d10 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49  is passed NULL I
16d20 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e  n this case.  An
16d30 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e   example of usin
16d40 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67  g this.** config
16d50 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63  uration option c
16d60 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68  an be seen in th
16d70 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63  e "test_sqllog.c
16d80 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e  " source file in
16d90 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61  .** the canonica
16da0 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  l SQLite source 
16db0 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tree.</dd>.**.**
16dc0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16dd0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
16de0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16df0 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c  G_MMAP_SIZE.** <
16e00 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  dd>^SQLITE_CONFI
16e10 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65  G_MMAP_SIZE take
16e20 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74  s two 64-bit int
16e30 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e  eger (sqlite3_in
16e40 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74  t64) values.** t
16e50 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61  hat are the defa
16e60 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  ult mmap size li
16e70 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74  mit (the default
16e80 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20   setting for.** 
16e90 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
16ea0 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69  e]) and the maxi
16eb0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
16ec0 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20   size limit..** 
16ed0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
16ee0 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72  ting can be over
16ef0 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64  ridden by each d
16f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16f10 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68  on using.** eith
16f20 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d  er the [PRAGMA m
16f30 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e  map_size] comman
16f40 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74  d, or by using t
16f50 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
16f60 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
16f70 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28  ile control.  ^(
16f80 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  The maximum allo
16f90 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
16fa0 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c   will be silentl
16fb0 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e  y truncated if n
16fc0 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74  ecessary so that
16fd0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63   it does not exc
16fe0 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  eed the.** compi
16ff0 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
17000 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
17010 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
17020 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
17030 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
17040 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
17050 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
17060 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
17070 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
17080 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
17090 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
170a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
170b0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
170c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
170d0 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
170e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
170f0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
17100 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  E.** <dd>^The SQ
17110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
17120 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f  2_HEAPSIZE optio
17130 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
17140 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
17150 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72  .** compiled for
17160 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68   Windows with th
17170 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  e [SQLITE_WIN32_
17180 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63  MALLOC] pre-proc
17190 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64  essor macro.** d
171a0 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f  efined. ^SQLITE_
171b0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
171c0 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32  PSIZE takes a 32
171d0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
171e0 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74  teger value.** t
171f0 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
17200 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
17210 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65  f the created he
17220 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ap..**.** [[SQLI
17230 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
17240 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _HDRSZ]].** <dt>
17250 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
17260 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64  ACHE_HDRSZ.** <d
17270 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
17280 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
17290 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
172a0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
172b0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  r which.** is a 
172c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
172d0 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73  teger and writes
172e0 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
172f0 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  er the number of
17300 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20   extra.** bytes 
17310 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65  per page require
17320 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20  d for each page 
17330 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  in [SQLITE_CONFI
17340 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
17350 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65   The amount of e
17360 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69  xtra space requi
17370 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64  red can change d
17380 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
17390 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72  compiler,.** tar
173a0 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e  get platform, an
173b0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
173c0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
173d0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a  _CONFIG_PMASZ]].
173e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
173f0 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64  NFIG_PMASZ.** <d
17400 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
17410 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f  NFIG_PMASZ optio
17420 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
17430 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
17440 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e  .** is an unsign
17450 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73  ed integer and s
17460 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d  ets the "Minimum
17470 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74   PMA Size" for t
17480 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  he multithreaded
17490 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68  .** sorter to th
174a0 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65  at integer.  The
174b0 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d   default minimum
174c0 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74   PMA Size is set
174d0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
174e0 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d  TE_SORTER_PMASZ]
174f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17500 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61  tion.  New threa
17510 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a  ds are launched.
17520 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20  ** to help with 
17530 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20  sort operations 
17540 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64  when multithread
17550 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73  ed sorting.** is
17560 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20   enabled (using 
17570 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65  the [PRAGMA thre
17580 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e  ads] command) an
17590 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  d the amount of 
175a0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  content.** to be
175b0 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20   sorted exceeds 
175c0 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69  the page size ti
175d0 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  mes the minimum 
175e0 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d  of the.** [PRAGM
175f0 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65  A cache_size] se
17600 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76  tting and this v
17610 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  alue..**.** [[SQ
17620 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
17630 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20  JRNL_SPILL]].** 
17640 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17650 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
17660 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
17670 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17680 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e  RNL_SPILL option
17690 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
176a0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
176b0 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b  ** becomes the [
176c0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
176d0 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b  l] spill-to-disk
176e0 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a   threshold.  .**
176f0 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [Statement jour
17700 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69  nals] are held i
17710 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74  n memory until t
17720 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79  heir size (in by
17730 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20  tes).** exceeds 
17740 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20  this threshold, 
17750 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74  at which point t
17760 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20  hey are written 
17770 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69  to disk..** Or i
17780 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20  f the threshold 
17790 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74  is -1, statement
177a0 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c   journals are al
177b0 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63  ways held.** exc
177c0 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f  lusively in memo
177d0 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e  ry..** Since man
177e0 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  y statement jour
177f0 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d  nals never becom
17800 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67  e large, setting
17810 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68   the spill.** th
17820 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c  reshold to a val
17830 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42  ue such as 64KiB
17840 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64   can greatly red
17850 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  uce the amount o
17860 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65  f.** I/O require
17870 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61  d to support sta
17880 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e  tement rollback.
17890 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
178a0 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73  value for this s
178b0 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f  etting is contro
178c0 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  lled by the.** [
178d0 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f  SQLITE_STMTJRNL_
178e0 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74  SPILL] compile-t
178f0 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ime option..**.*
17900 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17910 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45  G_SORTERREF_SIZE
17920 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17930 5f 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45  _CONFIG_SORTERRE
17940 46 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68  F_SIZE.** <dd>Th
17950 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17960 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20 6f  SORTERREF_SIZE o
17970 70 74 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20  ption accepts a 
17980 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
17990 0a 2a 2a 20 6f 66 20 74 79 70 65 20 28 69 6e 74  .** of type (int
179a0 29 20 2d 20 74 68 65 20 6e 65 77 20 76 61 6c 75  ) - the new valu
179b0 65 20 6f 66 20 74 68 65 20 73 6f 72 74 65 72 2d  e of the sorter-
179c0 72 65 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74  reference size t
179d0 68 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 73 75  hreshold..** Usu
179e0 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c 69 74  ally, when SQLit
179f0 65 20 75 73 65 73 20 61 6e 20 65 78 74 65 72 6e  e uses an extern
17a00 61 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64 65 72  al sort to order
17a10 20 72 65 63 6f 72 64 73 20 61 63 63 6f 72 64 69   records accordi
17a20 6e 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 44 45  ng.** to an ORDE
17a30 52 20 42 59 20 63 6c 61 75 73 65 2c 20 61 6c 6c  R BY clause, all
17a40 20 66 69 65 6c 64 73 20 72 65 71 75 69 72 65 64   fields required
17a50 20 62 79 20 74 68 65 20 63 61 6c 6c 65 72 20 61   by the caller a
17a60 72 65 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68  re present in th
17a70 65 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65 63 6f  e.** sorted reco
17a80 72 64 73 2e 20 48 6f 77 65 76 65 72 2c 20 69 66  rds. However, if
17a90 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
17aa0 65 73 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20  es based on the 
17ab0 64 65 63 6c 61 72 65 64 20 74 79 70 65 0a 2a 2a  declared type.**
17ac0 20 6f 66 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   of a table colu
17ad0 6d 6e 20 74 68 61 74 20 69 74 73 20 76 61 6c 75  mn that its valu
17ae0 65 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f  es are likely to
17af0 20 62 65 20 76 65 72 79 20 6c 61 72 67 65 20 2d   be very large -
17b00 20 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61 6e 20   larger.** than 
17b10 74 68 65 20 63 6f 6e 66 69 67 75 72 65 64 20 73  the configured s
17b20 6f 72 74 65 72 2d 72 65 66 65 72 65 6e 63 65 20  orter-reference 
17b30 73 69 7a 65 20 74 68 72 65 73 68 6f 6c 64 20 2d  size threshold -
17b40 20 74 68 65 6e 20 61 20 72 65 66 65 72 65 6e 63   then a referenc
17b50 65 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64 20 69  e.** is stored i
17b60 6e 20 65 61 63 68 20 73 6f 72 74 65 64 20 72 65  n each sorted re
17b70 63 6f 72 64 20 61 6e 64 20 74 68 65 20 72 65 71  cord and the req
17b80 75 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76 61 6c  uired column val
17b90 75 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 66 72  ues loaded.** fr
17ba0 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20  om the database 
17bb0 61 73 20 72 65 63 6f 72 64 73 20 61 72 65 20 72  as records are r
17bc0 65 74 75 72 6e 65 64 20 69 6e 20 73 6f 72 74 65  eturned in sorte
17bd0 64 20 6f 72 64 65 72 2e 20 54 68 65 20 64 65 66  d order. The def
17be0 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 66 6f  ault.** value fo
17bf0 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  r this option is
17c00 20 74 6f 20 6e 65 76 65 72 20 75 73 65 20 74 68   to never use th
17c10 69 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e  is optimization.
17c20 20 53 70 65 63 69 66 79 69 6e 67 20 61 20 0a 2a   Specifying a .*
17c30 2a 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  * negative value
17c40 20 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e   for this option
17c50 20 72 65 73 74 6f 72 65 73 20 74 68 65 20 64 65   restores the de
17c60 66 61 75 6c 74 20 62 65 68 61 76 69 6f 75 72 2e  fault behaviour.
17c70 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
17c80 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
17c90 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
17ca0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
17cb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
17cc0 4c 45 5f 53 4f 52 54 45 52 5f 52 45 46 45 52 45  LE_SORTER_REFERE
17cd0 4e 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  NCES] compile-ti
17ce0 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f  me option..** </
17cf0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
17d00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
17d10 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
17d20 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
17d30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
17d40 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
17d50 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
17d60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17d70 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
17d80 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
17d90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17da0 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
17db0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
17dc0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
17dd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17de0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
17df0 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
17e00 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
17e10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17e20 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
17e30 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65    6  /* No longe
17e40 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
17e50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17e60 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
17e70 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
17e80 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
17e90 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17ea0 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
17eb0 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
17ec0 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
17ed0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17ee0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
17ef0 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
17f00 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
17f10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
17f20 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
17f30 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
17f40 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
17f50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17f60 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
17f70 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
17f80 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
17f90 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
17fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
17fb0 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
17fc0 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
17fd0 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
17fe0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
17ff0 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
18000 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18010 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
18020 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
18030 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
18040 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18050 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
18060 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
18070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18080 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
18090 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
180a0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
180b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
180c0 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
180d0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
180e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
180f0 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
18100 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
18110 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
18120 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18130 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
18140 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
18150 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
18160 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18170 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
18180 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
18190 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
181a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
181b0 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
181c0 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
181d0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
181e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
181f0 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
18200 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
18210 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
18220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18230 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
18240 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
18250 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
18260 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18270 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
18280 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
18290 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
182a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
182b0 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
182c0 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
182d0 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
182e0 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  a */.#define SQL
182f0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
18300 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32  RNL_SPILL      2
18310 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  6  /* int nByte 
18320 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18330 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d  E_CONFIG_SMALL_M
18340 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20  ALLOC        27 
18350 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
18360 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18370 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53  NFIG_SORTERREF_S
18380 49 5a 45 20 20 20 20 20 20 32 38 20 20 2f 2a 20  IZE      28  /* 
18390 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a  int nByte */../*
183a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
183b0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
183c0 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
183d0 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
183e0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
183f0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
18400 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
18410 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
18420 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
18430 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
18440 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
18450 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
18460 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
18470 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
18480 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
18490 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
184a0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
184b0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
184c0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
184d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
184e0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
184f0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
18500 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
18510 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
18520 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
18530 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
18540 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
18550 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
18560 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
18570 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
18580 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
18590 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
185a0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
185b0 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
185c0 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
185d0 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
185e0 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
185f0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
18600 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
18610 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
18620 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
18630 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
18640 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
18650 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
18660 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
18670 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
18680 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
18690 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
186a0 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
186b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
186c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
186d0 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
186e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
186f0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
18700 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
18710 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
18720 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
18730 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
18740 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
18750 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
18760 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
18770 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
18780 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
18790 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
187a0 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
187b0 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
187c0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
187d0 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
187e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
187f0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
18800 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
18810 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
18820 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
18830 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
18840 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
18850 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
18860 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
18870 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
18880 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18890 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
188a0 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
188b0 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
188c0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
188d0 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
188e0 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
188f0 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
18900 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
18910 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
18920 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18930 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
18940 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
18950 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
18960 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
18970 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
18980 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
18990 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
189a0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
189b0 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
189c0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
189d0 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
189e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
189f0 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
18a00 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
18a10 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
18a20 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
18a30 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
18a40 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
18a50 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
18a60 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
18a70 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
18a80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
18a90 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
18aa0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
18ab0 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
18ac0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
18ad0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
18ae0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
18af0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
18b00 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
18b10 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
18b20 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
18b30 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
18b40 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
18b50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
18b60 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
18b70 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18b80 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
18b90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
18ba0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
18bb0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
18bc0 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
18bd0 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
18be0 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
18bf0 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
18c00 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
18c10 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
18c20 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
18c30 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
18c40 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
18c50 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
18c60 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
18c70 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
18c80 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
18c90 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
18ca0 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
18cb0 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
18cc0 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
18cd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
18ce0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
18cf0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
18d00 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
18d10 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
18d20 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
18d30 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
18d40 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
18d50 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
18d60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18d70 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
18d80 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
18d90 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
18da0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
18db0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
18dc0 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
18dd0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18de0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18df0 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
18e00 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
18e10 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
18e20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
18e30 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
18e40 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
18e50 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
18e60 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18e70 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
18e80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18e90 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
18ea0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
18eb0 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
18ec0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
18ed0 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
18ee0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
18ef0 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
18f00 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
18f10 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18f20 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
18f30 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
18f40 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
18f50 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
18f60 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
18f70 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
18f80 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
18f90 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
18fa0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
18fb0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18fc0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
18fd0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
18fe0 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
18ff0 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
19000 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
19010 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
19020 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
19030 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
19040 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a  OKENIZER</dt>.**
19050 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
19060 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
19070 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
19080 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74  the two-argument
19090 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  .** version of t
190a0 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  he [fts3_tokeniz
190b0 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77  er()] function w
190c0 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20  hich is part of 
190d0 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75  the.** [FTS3] fu
190e0 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65  ll-text search e
190f0 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e  ngine extension.
19100 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
19110 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
19120 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
19130 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
19140 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
19150 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
19160 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b  disable fts3_tok
19170 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70  enizer() or.** p
19180 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
19190 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  e fts3_tokenizer
191a0 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  () or negative t
191b0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
191c0 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ing.** unchanged
191d0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
191e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
191f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
19200 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
19210 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
19220 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
19230 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f   whether fts3_to
19240 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62  kenizer is disab
19250 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
19260 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
19270 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
19280 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
19290 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
192a0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
192b0 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74  case the new set
192c0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
192d0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
192e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
192f0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19300 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e  E_LOAD_EXTENSION
19310 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19320 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
19330 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
19340 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c  disable the [sql
19350 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
19360 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ion()].** interf
19370 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c  ace independentl
19380 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65  y of the [load_e
19390 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20  xtension()] SQL 
193a0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  function..** The
193b0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
193c0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
193d0 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f  )] API enables o
193e0 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20  r disables both 
193f0 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71  the.** C-API [sq
19400 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
19410 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20  sion()] and the 
19420 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f  SQL function [lo
19430 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e  ad_extension()].
19440 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
19450 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
19460 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
19470 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20   When the first 
19480 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
19490 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c   interface is 1,
194a0 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43   then only the C
194b0 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c  -API is.** enabl
194c0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  ed and the SQL f
194d0 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20  unction remains 
194e0 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68  disabled.  If th
194f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19500 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65   to.** this inte
19510 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e  rface is 0, then
19520 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20   both the C-API 
19530 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
19540 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65  tion are disable
19550 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72  d..** If the fir
19560 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d  st argument is -
19570 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67  1, then no chang
19580 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73  es are made to s
19590 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74  tate of either t
195a0 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74  he.** C-API or t
195b0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
195c0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
195d0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
195e0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
195f0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
19600 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
19610 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
19620 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33  whether [sqlite3
19630 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
19640 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
19650 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
19660 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67  nabled following
19670 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
19680 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19690 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55  r may.** be a NU
196a0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77  LL pointer, in w
196b0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65  hich case the ne
196c0 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  w setting is not
196d0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a   reported back..
196e0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
196f0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
19700 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64  IG_MAINDBNAME</d
19710 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
19720 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
19730 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61  to change the na
19740 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22  me of the "main"
19750 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68   database.** sch
19760 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20  ema.  ^The sole 
19770 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
19780 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74  inter to a const
19790 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a  ant UTF8 string.
197a0 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
197b0 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68  come the new sch
197c0 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63  ema name in plac
197d0 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53  e of "main".  ^S
197e0 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  QLite.** does no
197f0 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  t make a copy of
19800 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63   the new main sc
19810 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67  hema name string
19820 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61  , so the applica
19830 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
19840 75 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67  ure that the arg
19850 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74  ument passed int
19860 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20  o this DBCONFIG 
19870 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e  option is unchan
19880 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74  ged.** until aft
19890 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  er the database 
198a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
198b0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
198c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
198d0 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e  ONFIG_NO_CKPT_ON
198e0 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  _CLOSE</dt>.** <
198f0 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65  dd> Usually, whe
19900 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20  n a database in 
19910 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73  wal mode is clos
19920 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66  ed or detached f
19930 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61  rom a .** databa
19940 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74  se handle, SQLit
19950 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73  e checks if this
19960 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20   will mean that 
19970 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f  there are now no
19980 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   .** connections
19990 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64   at all to the d
199a0 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20  atabase. If so, 
199b0 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68  it performs a ch
199c0 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65  eckpoint .** ope
199d0 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c  ration before cl
199e0 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63  osing the connec
199f0 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f  tion. This optio
19a00 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  n may be used to
19a10 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69  .** override thi
19a20 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65  s behaviour. The
19a30 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
19a40 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20   passed to this 
19a50 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  operation.** is 
19a60 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 70 6f 73  an integer - pos
19a70 69 74 69 76 65 20 74 6f 20 64 69 73 61 62 6c 65  itive to disable
19a80 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d   checkpoints-on-
19a90 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28  close, or zero (
19aa0 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20  the.** default) 
19ab0 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2c 20  to enable them, 
19ac0 61 6e 64 20 6e 65 67 61 74 69 76 65 20 74 6f 20  and negative to 
19ad0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
19ae0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
19af0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19b00 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
19b10 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  r to an integer.
19b20 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73  ** into which is
19b30 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
19b40 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
19b50 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d  her checkpoints-
19b60 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65  on-close.** have
19b70 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d   been disabled -
19b80 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e   0 if they are n
19b90 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69  ot disabled, 1 i
19ba0 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c  f they are..** <
19bb0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
19bc0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
19bd0 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a  NABLE_QPSG</dt>.
19be0 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c  ** <dd>^(The SQL
19bf0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19c00 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20  BLE_QPSG option 
19c10 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61  activates or dea
19c20 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20  ctivates.** the 
19c30 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 73  [query planner s
19c40 74 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e 74  tability guarant
19c50 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68 65  ee] (QPSG).  Whe
19c60 6e 20 74 68 65 20 51 50 53 47 20 69 73 20 61 63  n the QPSG is ac
19c70 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c  tive,.** a singl
19c80 65 20 53 51 4c 20 71 75 65 72 79 20 73 74 61 74  e SQL query stat
19c90 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79  ement will alway
19ca0 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 61  s use the same a
19cb0 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64 6c  lgorithm regardl
19cc0 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73  ess.** of values
19cd0 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
19ce0 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51 50  eters].)^ The QP
19cf0 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d 65  SG disables some
19d00 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61 74   query optimizat
19d10 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f  ions.** that loo
19d20 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65 73 20  k at the values 
19d30 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  of bound paramet
19d40 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20 6d  ers, which can m
19d50 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65 73  ake some queries
19d60 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75 74  .** slower.  But
19d70 20 74 68 65 20 51 50 53 47 20 68 61 73 20 74 68   the QPSG has th
19d80 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20 6d  e advantage of m
19d90 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c 65 20  ore predictable 
19da0 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68 0a  behavior.  With.
19db0 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63 74 69  ** the QPSG acti
19dc0 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ve, SQLite will 
19dd0 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73  always use the s
19de0 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20 69  ame query plan i
19df0 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a 2a  n the field as.*
19e00 2a 20 77 61 73 20 75 73 65 64 20 64 75 72 69 6e  * was used durin
19e10 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68 65  g testing in the
19e20 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66 69 72   lab..** The fir
19e30 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
19e40 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 61  his setting is a
19e50 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
19e60 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
19e70 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c 20 70 6f  .** the QPSG, po
19e80 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
19e90 20 51 50 53 47 2c 20 6f 72 20 6e 65 67 61 74 69   QPSG, or negati
19ea0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
19eb0 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61  setting.** uncha
19ec0 6e 67 65 64 2e 20 54 68 65 20 73 65 63 6f 6e 64  nged. The second
19ed0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19ee0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19ef0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19f00 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
19f10 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19f20 65 20 77 68 65 74 68 65 72 20 74 68 65 20 51 50  e whether the QP
19f30 53 47 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f  SG is disabled o
19f40 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
19f50 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
19f60 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
19f70 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
19f80 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50  NFIG_TRIGGER_EQP
19f90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79  </dt>.** <dd> By
19fa0 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 6f 75   default, the ou
19fb0 74 70 75 74 20 6f 66 20 45 58 50 4c 41 49 4e 20  tput of EXPLAIN 
19fc0 51 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61  QUERY PLAN comma
19fd0 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a  nds does not .**
19fe0 20 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 74 20   include output 
19ff0 66 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 69 6f  for any operatio
1a000 6e 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ns performed by 
1a010 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
1a020 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e  . This.** option
1a030 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
1a040 6f 72 20 63 6c 65 61 72 20 28 74 68 65 20 64 65  or clear (the de
1a050 66 61 75 6c 74 29 20 61 20 66 6c 61 67 20 74 68  fault) a flag th
1a060 61 74 20 67 6f 76 65 72 6e 73 20 74 68 69 73 0a  at governs this.
1a070 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 68 65  ** behavior. The
1a080 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1a090 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20   passed to this 
1a0a0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
1a0b0 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70 6f 73  integer -.** pos
1a0c0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
1a0d0 6f 75 74 70 75 74 20 66 6f 72 20 74 72 69 67 67  output for trigg
1a0e0 65 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20  er programs, or 
1a0f0 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20  zero to disable 
1a100 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61 74 69  it,.** or negati
1a110 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
1a120 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
1a130 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
1a140 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
1a150 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
1a160 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
1a170 20 69 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20   is written .** 
1a180 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
1a190 74 65 20 77 68 65 74 68 65 72 20 6f 75 74 70 75  te whether outpu
1a1a0 74 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 20 68  t-for-triggers h
1a1b0 61 73 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  as been disabled
1a1c0 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 20 69   - 0 if .** it i
1a1d0 73 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20  s not disabled, 
1a1e0 31 20 69 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a  1 if it is.  .**
1a1f0 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a   </dd>.** </dl>.
1a200 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a210 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
1a220 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  BNAME           
1a230 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63   1000 /* const c
1a240 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  har* */.#define 
1a250 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1a260 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20  LOOKASIDE       
1a270 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f        1001 /* vo
1a280 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
1a290 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1a2a0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
1a2b0 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30  EY           100
1a2c0 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  2 /* int int* */
1a2d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a2e0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
1a2f0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31  TRIGGER        1
1a300 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  003 /* int int* 
1a310 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a320 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1a330 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
1a340 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74   1004 /* int int
1a350 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1a360 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1a370 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
1a380 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69  ON 1005 /* int i
1a390 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1a3a0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e  QLITE_DBCONFIG_N
1a3b0 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20  O_CKPT_ON_CLOSE 
1a3c0 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74       1006 /* int
1a3d0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1a3e0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1a3f0 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20 20  _ENABLE_QPSG    
1a400 20 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20 69         1007 /* i
1a410 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1a420 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1a430 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 20 20  IG_TRIGGER_EQP  
1a440 20 20 20 20 20 20 20 20 20 31 30 30 38 20 2f 2a           1008 /*
1a450 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1a460 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1a470 4e 46 49 47 5f 4d 41 58 20 20 20 20 20 20 20 20  NFIG_MAX        
1a480 20 20 20 20 20 20 20 20 20 20 20 31 30 30 38 20             1008 
1a490 2f 2a 20 4c 61 72 67 65 73 74 20 44 42 43 4f 4e  /* Largest DBCON
1a4a0 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  FIG */../*.** CA
1a4b0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
1a4c0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
1a4d0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
1a4e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1a4f0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
1a500 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
1a510 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
1a520 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
1a530 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
1a540 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
1a550 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
1a560 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
1a570 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
1a580 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
1a590 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1a5a0 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
1a5b0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1a5c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1a5d0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
1a5e0 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
1a5f0 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
1a600 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
1a610 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
1a620 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1a630 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
1a640 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74  ry in most SQLit
1a650 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74  e tables (except
1a660 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f   for [WITHOUT RO
1a670 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20  WID] tables).** 
1a680 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
1a690 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
1a6a0 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
1a6b0 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
1a6c0 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
1a6d0 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
1a6e0 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
1a6f0 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
1a700 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
1a710 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
1a720 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
1a730 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
1a740 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
1a750 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
1a760 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
1a770 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
1a780 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
1a790 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
1a7a0 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
1a7b0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
1a7c0 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
1a7d0 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
1a7e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61   ^The sqlite3_la
1a7f0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a800 44 29 20 69 6e 74 65 72 66 61 63 65 20 75 73 75  D) interface usu
1a810 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
1a820 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20 74   [rowid] of.** t
1a830 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
1a840 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
1a850 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20  T] into a rowid 
1a860 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61  table or [virtua
1a870 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64  l table].** on d
1a880 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a890 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 20 69  on D. ^Inserts i
1a8a0 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  nto [WITHOUT ROW
1a8b0 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e  ID] tables are n
1a8c0 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e 20  ot.** recorded. 
1a8d0 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
1a8e0 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f  l [INSERT]s into
1a8f0 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 68 61   rowid tables ha
1a900 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
1a910 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74 61   .** on the data
1a920 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a930 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  D, then sqlite3_
1a940 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1a950 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a 2a 2a  d(D) returns .**
1a960 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20   zero..**.** As 
1a970 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 73 65  well as being se
1a980 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  t automatically 
1a990 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e 73 65  as rows are inse
1a9a0 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61 62 61  rted into databa
1a9b0 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74 68  se.** tables, th
1a9c0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a9d0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
1a9e0 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65 78 70  n may be set exp
1a9f0 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b 73  licitly by.** [s
1aa00 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f  qlite3_set_last_
1aa10 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
1aa20 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74 75  **.** Some virtu
1aa30 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
1aa40 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e 53  ntations may INS
1aa50 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 72 6f  ERT rows into ro
1aa60 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a 2a 2a  wid tables as.**
1aa70 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74 74   part of committ
1aa80 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
1aa90 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73 68  n (e.g. to flush
1aaa0 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61 74 65   data accumulate
1aab0 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74  d in memory.** t
1aac0 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 69 73  o disk). In this
1aad0 20 63 61 73 65 20 73 75 62 73 65 71 75 65 6e 74   case subsequent
1aae0 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 20 66   calls to this f
1aaf0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 74  unction return t
1ab00 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73 6f  he rowid.** asso
1ab10 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 73  ciated with thes
1ab20 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45 52  e internal INSER
1ab30 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68  T operations, wh
1ab40 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a 2a  ich leads to .**
1ab50 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72 65 73   unintuitive res
1ab60 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 74 61  ults. Virtual ta
1ab70 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
1ab80 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72 69 74  ons that do writ
1ab90 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74 61  e to rowid.** ta
1aba0 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77 61 79  bles in this way
1abb0 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69 73 20   can avoid this 
1abc0 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 74 6f  problem by resto
1abd0 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61  ring the origina
1abe0 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c 75  l .** rowid valu
1abf0 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
1ac00 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
1ac10 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f 72 65  _rowid()] before
1ac20 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20 63   returning .** c
1ac30 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 75 73  ontrol to the us
1ac40 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  er..**.** ^(If a
1ac50 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72  n [INSERT] occur
1ac60 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  s within a trigg
1ac70 65 72 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  er then this rou
1ac80 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72 65  tine will .** re
1ac90 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
1aca0 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
1acb0 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20   row as long as 
1acc0 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20 0a  the trigger is .
1acd0 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65  ** running. Once
1ace0 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f   the trigger pro
1acf0 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 20 76  gram ends, the v
1ad00 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
1ad10 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
1ad20 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
1ad30 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
1ad40 74 68 65 20 74 72 69 67 67 65 72 20 77 61 73 20  the trigger was 
1ad50 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  fired.)^.**.** ^
1ad60 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
1ad70 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
1ad80 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
1ad90 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
1ada0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
1adb0 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
1adc0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
1add0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
1ade0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
1adf0 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
1ae00 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
1ae10 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
1ae20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
1ae30 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
1ae40 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
1ae50 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
1ae60 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
1ae70 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
1ae80 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
1ae90 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
1aea0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
1aeb0 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
1aec0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
1aed0 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
1aee0 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
1aef0 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
1af00 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
1af10 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
1af20 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
1af30 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
1af40 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
1af50 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
1af60 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
1af70 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
1af80 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
1af90 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
1afa0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
1afb0 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
1afc0 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
1afd0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
1afe0 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
1aff0 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
1b000 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
1b010 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
1b020 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
1b030 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
1b040 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
1b050 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
1b060 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
1b070 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
1b080 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
1b090 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
1b0a0 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
1b0b0 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
1b0c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b0d0 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
1b0e0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1b0f0 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
1b100 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
1b110 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
1b120 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
1b130 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
1b140 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
1b150 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1b160 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1b170 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
1b180 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1b190 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
1b1a0 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
1b1b0 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
1b1c0 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
1b1d0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
1b1e0 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
1b1f0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
1b200 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1b210 41 50 49 33 52 45 46 3a 20 53 65 74 20 74 68 65  API3REF: Set the
1b220 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
1b230 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45 54  id value..** MET
1b240 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1b250 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
1b260 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  et_last_insert_r
1b270 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68 6f  owid(D, R) metho
1b280 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70 70  d allows the app
1b290 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 73  lication to.** s
1b2a0 65 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  et the value ret
1b2b0 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  urned by calling
1b2c0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
1b2d0 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74 6f  sert_rowid(D) to
1b2e0 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20 69   R .** without i
1b2f0 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20 69  nserting a row i
1b300 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
1b310 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
1b320 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
1b330 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
1b340 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
1b350 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b360 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62  : Count The Numb
1b370 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
1b380 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ied.** METHOD: s
1b390 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1b3a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1b3b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1b3c0 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c  f rows modified,
1b3d0 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20   inserted or.** 
1b3e0 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
1b3f0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
1b400 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
1b410 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a  PDATE or DELETE.
1b420 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20  ** statement on 
1b430 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1b440 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65  nection specifie
1b450 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61  d by the only pa
1b460 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65  rameter..** ^Exe
1b470 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
1b480 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
1b490 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
1b4a0 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65  modify the value
1b4b0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
1b4c0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
1b4d0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67  *.** ^Only chang
1b4e0 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79  es made directly
1b4f0 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20   by the INSERT, 
1b500 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1b510 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a   statement are.*
1b520 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61  * considered - a
1b530 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
1b540 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41   caused by [CREA
1b550 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
1b560 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72  ggers], .** [for
1b570 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
1b580 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63  ] or [REPLACE] c
1b590 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
1b5a0 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75  tion are not cou
1b5b0 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61  nted..** .** Cha
1b5c0 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
1b5d0 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
1b5e0 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54  ted by .** [INST
1b5f0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c  EAD OF trigger |
1b600 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
1b610 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  gers] are not co
1b620 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75  unted. ^The valu
1b630 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  e .** returned b
1b640 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
1b650 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  s() immediately 
1b660 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c  after an INSERT,
1b670 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44   UPDATE or .** D
1b680 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1b690 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73  run on a view is
1b6a0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e   always zero. On
1b6b0 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  ly changes made 
1b6c0 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c  to real .** tabl
1b6d0 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
1b6e0 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65  **.** Things are
1b6f0 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65   more complicate
1b700 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33  d if the sqlite3
1b710 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
1b720 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74  ion is.** execut
1b730 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67  ed while a trigg
1b740 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75  er program is ru
1b750 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20  nning. This may 
1b760 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a  happen if the.**
1b770 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68   program uses th
1b780 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1b790 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69   function], or i
1b7a0 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c  f some other cal
1b7b0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
1b7c0 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65  n invokes sqlite
1b7d0 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65  3_changes() dire
1b7e0 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c  ctly. Essentiall
1b7f0 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  y:.** .** <ul>.*
1b800 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72  *   <li> ^(Befor
1b810 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69  e entering a tri
1b820 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65  gger program the
1b830 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1b840 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c  by.**        sql
1b850 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
1b860 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64  unction is saved
1b870 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67  . After the trig
1b880 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20  ger program .** 
1b890 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73         has finis
1b8a0 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61  hed, the origina
1b8b0 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f  l value is resto
1b8c0 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20  red.)^.** .**   
1b8d0 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20  <li> ^(Within a 
1b8e0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1b8f0 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44  each INSERT, UPD
1b900 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a  ATE and DELETE .
1b910 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d  **        statem
1b920 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c  ent sets the val
1b930 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1b940 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1b950 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e   .**        upon
1b960 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e   completion as n
1b970 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65  ormal. Of course
1b980 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c  , this value wil
1b990 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a  l not include .*
1b9a0 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61  *        any cha
1b9b0 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62  nges performed b
1b9c0 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20  y sub-triggers, 
1b9d0 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  as the sqlite3_c
1b9e0 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20  hanges() .**    
1b9f0 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62      value will b
1ba00 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74  e saved and rest
1ba10 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20  ored after each 
1ba20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20  sub-trigger has 
1ba30 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  run.)^.** </ul>.
1ba40 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61  ** .** ^This mea
1ba50 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63  ns that if the c
1ba60 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1ba70 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61  ction (or simila
1ba80 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79  r) is used.** by
1ba90 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52   the first INSER
1baa0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1bab0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
1bac0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
1bad0 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  it .** returns t
1bae0 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20  he value as set 
1baf0 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67  when the calling
1bb00 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e   statement began
1bb10 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
1bb20 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79  If it is used by
1bb30 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73   the second or s
1bb40 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73  ubsequent such s
1bb50 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1bb60 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72  a trigger .** pr
1bb70 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65  ogram, the value
1bb80 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63   returned reflec
1bb90 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ts the number of
1bba0 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62   rows modified b
1bbb0 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f  y the .** previo
1bbc0 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  us INSERT, UPDAT
1bbd0 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
1bbe0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
1bbf0 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
1bc00 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
1bc10 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1bc20 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1bc30 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
1bc40 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1bc50 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
1bc60 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1bc70 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
1bc80 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1bc90 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1bca0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1bcb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bcc0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1bcd0 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
1bce0 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1bcf0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1bd00 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
1bd10 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1bd20 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
1bd30 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1bd40 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1bd50 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
1bd60 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
1bd70 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
1bd80 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1bd90 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1bda0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  n returns the to
1bdb0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  tal number of ro
1bdc0 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64  ws inserted, mod
1bdd0 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  ified or.** dele
1bde0 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45  ted by all [INSE
1bdf0 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72  RT], [UPDATE] or
1be00 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
1be10 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a  ents completed.*
1be20 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  * since the data
1be30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1be40 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c  was opened, incl
1be50 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63  uding those exec
1be60 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  uted as.** part 
1be70 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  of trigger progr
1be80 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20  ams. ^Executing 
1be90 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
1bea0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  f SQL statement.
1beb0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65  ** does not affe
1bec0 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ct the value ret
1bed0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1bee0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1bef0 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65  ..** .** ^Change
1bf00 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  s made as part o
1bf10 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  f [foreign key a
1bf20 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c  ctions] are incl
1bf30 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63  uded in the.** c
1bf40 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20  ount, but those 
1bf50 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
1bf60 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
1bf70 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
1bf80 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67  e.** not. ^Chang
1bf90 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
1bfa0 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
1bfb0 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20  d by INSTEAD OF 
1bfc0 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65  triggers .** are
1bfd0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
1bfe0 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68   .** See also th
1bff0 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
1c000 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
1c010 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
1c020 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
1c030 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
1c040 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1c050 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
1c060 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1c070 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
1c080 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
1c090 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c0a0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
1c0b0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1c0c0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1c0d0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
1c0e0 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
1c0f0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1c100 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1c110 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
1c120 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
1c130 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1c140 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
1c150 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
1c160 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44   Query.** METHOD
1c170 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1c180 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
1c190 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
1c1a0 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
1c1b0 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
1c1c0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
1c1d0 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
1c1e0 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
1c1f0 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
1c200 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
1c210 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
1c220 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
1c230 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
1c240 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
1c250 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
1c260 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
1c270 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
1c280 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
1c290 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
1c2a0 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
1c2b0 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
1c2c0 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
1c2d0 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
1c2e0 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
1c2f0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
1c300 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
1c310 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
1c320 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
1c330 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
1c340 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
1c350 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c360 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
1c370 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
1c380 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
1c390 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
1c3a0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
1c3b0 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
1c3c0 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
1c3d0 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
1c3e0 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
1c3f0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1c400 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
1c410 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
1c420 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
1c430 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
1c440 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
1c450 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
1c460 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
1c470 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
1c480 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
1c490 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
1c4a0 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
1c4b0 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
1c4c0 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
1c4d0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
1c4e0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
1c4f0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
1c500 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
1c510 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
1c520 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
1c530 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
1c540 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
1c550 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
1c560 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
1c570 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1c580 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
1c590 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
1c5a0 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
1c5b0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
1c5c0 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
1c5d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1c5e0 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
1c5f0 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
1c600 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1c610 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1c620 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1c630 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
1c640 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
1c650 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
1c660 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
1c670 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
1c680 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
1c690 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
1c6a0 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
1c6b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1c6c0 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
1c6d0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1c6e0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1c6f0 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
1c700 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
1c710 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
1c720 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
1c730 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
1c740 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
1c750 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
1c760 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1c770 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
1c780 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
1c790 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
1c7a0 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
1c7b0 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
1c7c0 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
1c7d0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1c7e0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1c7f0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1c800 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
1c810 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20  eturns..*/.void 
1c820 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1c830 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
1c840 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
1c850 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
1c860 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
1c870 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
1c880 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1c890 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
1c8a0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
1c8b0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
1c8c0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
1c8d0 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
1c8e0 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
1c8f0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
1c900 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
1c910 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
1c920 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
1c930 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
1c940 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
1c950 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
1c960 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1c970 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
1c980 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
1c990 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
1c9a0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
1c9b0 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
1c9c0 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
1c9d0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
1c9e0 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
1c9f0 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
1ca00 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
1ca10 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
1ca20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
1ca30 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
1ca40 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
1ca50 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
1ca60 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
1ca70 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
1ca80 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
1ca90 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
1caa0 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
1cab0 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
1cac0 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
1cad0 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
1cae0 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
1caf0 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
1cb00 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
1cb10 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
1cb20 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
1cb30 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
1cb40 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
1cb50 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
1cb60 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
1cb70 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
1cb80 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1cb90 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
1cba0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
1cbb0 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
1cbc0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
1cbd0 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
1cbe0 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
1cbf0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
1cc00 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1cc10 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
1cc20 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
1cc30 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
1cc40 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
1cc50 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
1cc60 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
1cc70 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
1cc80 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
1cc90 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1cca0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
1ccb0 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
1ccc0 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
1ccd0 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
1cce0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
1ccf0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
1cd00 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
1cd10 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
1cd20 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
1cd30 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
1cd40 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
1cd50 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1cd60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
1cd70 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
1cd80 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
1cd90 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1cda0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
1cdb0 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
1cdc0 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
1cdd0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
1cde0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
1cdf0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1ce00 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1ce10 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
1ce20 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1ce30 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1ce40 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
1ce50 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1ce60 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
1ce70 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
1ce80 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
1ce90 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
1cea0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
1ceb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1cec0 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
1ced0 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
1cee0 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
1cef0 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
1cf00 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
1cf10 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45  USY Errors.** KE
1cf20 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61  YWORDS: {busy-ha
1cf30 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20  ndler callback} 
1cf40 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a  {busy handler}.*
1cf50 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1cf60 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
1cf70 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1cf80 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65  r(D,X,P) routine
1cf90 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b   sets a callback
1cfa0 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74   function X.** t
1cfb0 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
1cfc0 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65  oked with argume
1cfd0 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a  nt P whenever.**
1cfe0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
1cff0 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20  ade to access a 
1d000 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
1d010 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a  ssociated with.*
1d020 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1d030 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61  ection] D when a
1d040 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
1d050 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
1d060 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64  the table locked
1d070 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  ..** The sqlite3
1d080 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20  _busy_handler() 
1d090 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
1d0a0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a  d to implement.*
1d0b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  * [sqlite3_busy_
1d0c0 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b  timeout()] and [
1d0d0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1d0e0 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  out]..**.** ^If 
1d0f0 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  the busy callbac
1d100 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  k is NULL, then 
1d110 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1d120 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
1d130 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
1d140 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
1d150 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
1d160 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
1d170 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
1d180 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
1d190 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
1d1a0 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
1d1b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
1d1c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1d1d0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1d1e0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1d1f0 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
1d200 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
1d210 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
1d220 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
1d230 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
1d240 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1d250 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
1d260 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
1d270 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
1d280 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
1d290 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
1d2a0 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
1d2b0 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20   previously for 
1d2c0 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67  the same locking
1d2d0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
1d2e0 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
1d2f0 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
1d300 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
1d310 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
1d320 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
1d330 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1d340 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73  [SQLITE_BUSY] is
1d350 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20   returned.** to 
1d360 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
1d370 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
1d380 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1d390 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
1d3a0 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
1d3b0 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
1d3c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
1d3d0 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
1d3e0 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
1d3f0 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
1d400 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
1d410 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
1d420 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
1d430 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
1d440 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
1d450 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74  ntion. ^If SQLit
1d460 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61  e determines tha
1d470 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62  t invoking the b
1d480 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63  usy.** handler c
1d490 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
1d4a0 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69   deadlock, it wi
1d4b0 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20  ll go ahead and 
1d4c0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42  return [SQLITE_B
1d4d0 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61  USY].** to the a
1d4e0 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65  pplication inste
1d4f0 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74  ad of invoking t
1d500 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  he .** busy hand
1d510 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
1d520 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
1d530 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
1d540 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
1d550 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
1d560 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
1d570 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
1d580 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
1d590 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1d5a0 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
1d5b0 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
1d5c0 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
1d5d0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
1d5e0 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
1d5f0 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
1d600 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
1d610 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
1d620 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1d630 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
1d640 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
1d650 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
1d660 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
1d670 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
1d680 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
1d690 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
1d6a0 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
1d6b0 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
1d6c0 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
1d6d0 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
1d6e0 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
1d6f0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
1d700 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
1d710 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
1d720 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
1d730 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
1d740 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
1d750 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
1d760 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
1d770 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
1d780 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
1d790 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
1d7a0 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
1d7b0 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
1d7c0 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1d7d0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1d7e0 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
1d7f0 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
1d800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d810 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
1d820 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
1d830 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
1d840 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
1d850 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
1d860 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
1d870 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1d880 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61  out()].** or eva
1d890 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20  luating [PRAGMA 
1d8a0 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20  busy_timeout=N] 
1d8b0 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a  will change the.
1d8c0 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ** busy handler 
1d8d0 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61  and thus clear a
1d8e0 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ny previously se
1d8f0 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  t busy handler..
1d900 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63  **.** The busy c
1d910 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e  allback should n
1d920 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69  ot take any acti
1d930 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79  ons which modify
1d940 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1d950 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1d960 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1d970 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f  y handler.  In o
1d980 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74  ther words,.** t
1d990 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1d9a0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
1d9b0 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
1d9c0 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
1d9d0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
1d9e0 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
1d9f0 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
1da00 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
1da10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1da20 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
1da30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1da40 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1da50 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69  sy handler..*/.i
1da60 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1da70 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1da80 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  ,int(*)(void*,in
1da90 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  t),void*);../*.*
1daa0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
1dab0 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
1dac0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1dad0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  3.**.** ^This ro
1dae0 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
1daf0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1db00 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
1db10 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
1db20 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
1db30 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
1db40 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
1db50 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
1db60 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
1db70 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
1db80 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
1db90 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1dba0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1dbb0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
1dbc0 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
1dbd0 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1dbe0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1dbf0 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
1dc00 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
1dc10 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
1dc20 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
1dc30 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
1dc40 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  E_BUSY]..**.** ^
1dc50 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
1dc60 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
1dc70 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
1dc80 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
1dc90 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
1dca0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
1dcb0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1dcc0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1dcd0 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1dce0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
1dcf0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1dd00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e  onnection] at an
1dd10 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
1dd20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
1dd30 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
1dd40 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
1dd50 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1dd60 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
1dd70 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
1dd80 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
1dd90 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
1dda0 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
1ddb0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
1ddc0 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  :  [PRAGMA busy_
1ddd0 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20  timeout].*/.int 
1dde0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1ddf0 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
1de00 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
1de10 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
1de20 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
1de30 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
1de40 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
1de50 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ite3.**.** This 
1de60 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
1de70 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
1de80 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
1de90 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1dea0 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
1deb0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1dec0 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
1ded0 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
1dee0 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
1def0 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
1df00 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
1df10 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
1df20 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
1df30 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
1df40 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
1df50 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
1df60 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
1df70 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
1df80 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
1df90 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
1dfa0 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
1dfb0 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
1dfc0 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
1dfd0 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
1dfe0 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
1dff0 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
1e000 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
1e010 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
1e020 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
1e030 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
1e040 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
1e050 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
1e060 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
1e070 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
1e080 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1e090 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
1e0a0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
1e0b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1e0c0 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
1e0d0 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
1e0e0 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
1e0f0 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
1e100 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
1e110 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
1e120 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1e130 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
1e140 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
1e150 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
1e160 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
1e170 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
1e180 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
1e190 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
1e1a0 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
1e1b0 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
1e1c0 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
1e1d0 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
1e1e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1e1f0 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
1e200 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
1e210 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1e220 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
1e230 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1e240 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
1e250 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
1e260 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1e270 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
1e280 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
1e290 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
1e2a0 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
1e2b0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
1e2c0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
1e2d0 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
1e2e0 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
1e2f0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1e300 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
1e310 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
1e320 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
1e330 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
1e340 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
1e350 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1e360 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1e370 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1e380 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
1e390 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
1e3a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1e3b0 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
1e3c0 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
1e3d0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
1e3e0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
1e3f0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
1e400 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
1e410 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1e420 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
1e430 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
1e440 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
1e450 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
1e460 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
1e470 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
1e480 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
1e490 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
1e4a0 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
1e4b0 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
1e4c0 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
1e4d0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
1e4e0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
1e4f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e500 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1e510 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
1e520 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1e530 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
1e540 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1e550 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
1e560 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
1e570 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
1e580 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
1e590 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1e5a0 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
1e5b0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1e5c0 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
1e5d0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1e5e0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
1e5f0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
1e600 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
1e610 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
1e620 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
1e630 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e640 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
1e650 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
1e660 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1e670 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
1e680 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1e690 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
1e6a0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
1e6b0 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
1e6c0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
1e6d0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
1e6e0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
1e6f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
1e700 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
1e710 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
1e720 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
1e730 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
1e740 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
1e750 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
1e760 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
1e770 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
1e780 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
1e790 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
1e7a0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
1e7b0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
1e7c0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
1e7d0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
1e7e0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
1e7f0 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
1e800 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
1e810 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
1e820 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1e830 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
1e840 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
1e850 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
1e860 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1e870 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
1e880 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1e890 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
1e8a0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
1e8b0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
1e8c0 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
1e8d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1e8e0 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
1e8f0 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
1e900 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
1e910 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
1e920 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
1e930 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1e940 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
1e950 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
1e960 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
1e970 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
1e980 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
1e990 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
1e9a0 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
1e9b0 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
1e9c0 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
1e9d0 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
1e9e0 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
1e9f0 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
1ea00 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
1ea10 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
1ea20 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
1ea30 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
1ea40 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
1ea50 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
1ea60 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1ea70 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1ea80 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e  errmsg()]..*/.in
1ea90 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  t sqlite3_get_ta
1eaa0 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ble(.  sqlite3 *
1eab0 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
1eac0 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
1ead0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1eae0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53   *zSql,     /* S
1eaf0 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  QL to be evaluat
1eb00 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a  ed */.  char ***
1eb10 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a  pazResult,    /*
1eb20 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20   Results of the 
1eb30 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a  query */.  int *
1eb40 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20  pnRow,          
1eb50 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1eb60 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65  sult rows writte
1eb70 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20  n here */.  int 
1eb80 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20  *pnColumn,      
1eb90 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1eba0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72  esult columns wr
1ebb0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1ebc0 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20  char **pzErrmsg 
1ebd0 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
1ebe0 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
1ebf0 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  */.);.void sqlit
1ec00 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68  e3_free_table(ch
1ec10 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f  ar **result);../
1ec20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
1ec30 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20  ormatted String 
1ec40 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f  Printing Functio
1ec50 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1ec60 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b  outines are work
1ec70 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22  -alikes of the "
1ec80 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79  printf()" family
1ec90 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a   of functions.**
1eca0 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
1ecb0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
1ecc0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1ecd0 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20  understand most 
1ece0 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 66 6f  of the common fo
1ecf0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1ed00 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
1ed10 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 70 72  ndard library pr
1ed20 69 6e 74 66 28 29 20 0a 2a 2a 20 70 6c 75 73 20  intf() .** plus 
1ed30 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1ed40 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72  non-standard for
1ed50 6d 61 74 73 20 28 5b 25 71 5d 2c 20 5b 25 51 5d  mats ([%q], [%Q]
1ed60 2c 20 5b 25 77 5d 2c 20 61 6e 64 20 5b 25 7a 5d  , [%w], and [%z]
1ed70 29 2e 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 62  )..** See the [b
1ed80 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29  uilt-in printf()
1ed90 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
1eda0 66 6f 72 20 64 65 74 61 69 6c 73 2e 0a 2a 2a 0a  for details..**.
1edb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1edc0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1edd0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1ede0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1edf0 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1ee00 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1ee10 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1ee20 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 2e  te3_malloc64()].
1ee30 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1ee40 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1ee50 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1ee60 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1ee70 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1ee80 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1ee90 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1eea0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1eeb0 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1eec0 61 6c 6c 6f 63 36 34 28 29 5d 20 69 73 20 75 6e  alloc64()] is un
1eed0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1eee0 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
1eef0 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
1ef00 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
1ef10 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1ef20 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
1ef30 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
1ef40 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
1ef50 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
1ef60 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1ef70 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
1ef80 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1ef90 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
1efa0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
1efb0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
1efc0 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
1efd0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
1efe0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
1eff0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
1f000 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1f010 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
1f020 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
1f030 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
1f040 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
1f050 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
1f060 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1f070 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
1f080 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
1f090 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1f0a0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
1f0b0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
1f0c0 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
1f0d0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1f0e0 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
1f0f0 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
1f100 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
1f110 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
1f120 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
1f130 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
1f140 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
1f150 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1f160 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
1f170 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
1f180 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
1f190 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
1f1a0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
1f1b0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
1f1c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1f1d0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
1f1e0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
1f1f0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
1f200 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
1f210 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
1f220 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
1f230 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1f240 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
1f250 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
1f260 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
1f270 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
1f280 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1f290 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
1f2a0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
1f2b0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
1f2c0 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
1f2d0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
1f2e0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
1f2f0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
1f300 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
1f310 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
1f320 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
1f330 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
1f340 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1f350 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
1f360 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
1f370 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1f380 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ntf()..**.** See
1f390 20 61 6c 73 6f 3a 20 20 5b 62 75 69 6c 74 2d 69   also:  [built-i
1f3a0 6e 20 70 72 69 6e 74 66 28 29 5d 2c 20 5b 70 72  n printf()], [pr
1f3b0 69 6e 74 66 28 29 20 53 51 4c 20 66 75 6e 63 74  intf() SQL funct
1f3c0 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73 71  ion].*/.char *sq
1f3d0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
1f3e0 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
1f3f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1f400 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1f410 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68  r*, va_list);.ch
1f420 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
1f430 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
1f440 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
1f450 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1f460 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
1f470 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1f480 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
1f490 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1f4a0 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
1f4b0 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
1f4c0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
1f4d0 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
1f4e0 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
1f4f0 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
1f500 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
1f510 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
1f520 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
1f530 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
1f540 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
1f550 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
1f560 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
1f570 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1f580 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
1f590 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
1f5a0 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
1f5b0 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
1f5c0 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
1f5d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1f5e0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
1f5f0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1f600 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
1f610 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
1f620 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
1f630 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
1f640 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1f650 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
1f660 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
1f670 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
1f680 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
1f690 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
1f6a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1f6b0 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
1f6c0 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
1f6d0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1f6e0 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
1f6f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
1f700 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
1f710 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1f720 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1f730 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29  ite3_malloc64(N)
1f740 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a   routine works j
1f750 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69  ust like.** sqli
1f760 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78  te3_malloc(N) ex
1f770 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61  cept that N is a
1f780 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69  n unsigned 64-bi
1f790 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61  t integer instea
1f7a0 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64  d.** of a signed
1f7b0 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e   32-bit integer.
1f7c0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1f7d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
1f7e0 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
1f7f0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
1f800 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1f810 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1f820 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1f830 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
1f840 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
1f850 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
1f860 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
1f870 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
1f880 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
1f890 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1f8a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1f8b0 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
1f8c0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
1f8d0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
1f8e0 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
1f8f0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
1f900 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
1f910 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
1f920 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
1f930 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
1f940 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
1f950 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
1f960 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
1f970 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
1f980 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
1f990 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
1f9a0 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
1f9b0 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
1f9c0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1f9d0 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
1f9e0 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
1f9f0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
1fa00 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
1fa10 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
1fa20 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
1fa30 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1fa40 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1fa50 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
1fa60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
1fa70 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72  alloc(X,N) inter
1fa80 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
1fa90 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
1faa0 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
1fab0 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20  tion X to be at 
1fac0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a  least N bytes..*
1fad0 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61  * ^If the X para
1fae0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1faf0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a  _realloc(X,N).**
1fb00 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1fb10 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61  er then its beha
1fb20 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61  vior is identica
1fb30 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  l to calling.** 
1fb40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1fb50 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20  )..** ^If the N 
1fb60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1fb70 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1fb80 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  ) is zero or.** 
1fb90 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68  negative then th
1fba0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78  e behavior is ex
1fbb0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
1fbc0 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  s calling.** sql
1fbd0 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a  ite3_free(X)..**
1fbe0 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1fbf0 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61  c(X,N) returns a
1fc00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
1fc10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
1fc20 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
1fc30 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
1fc40 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66  r NULL if insuff
1fc50 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
1fc60 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e   available..** ^
1fc70 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
1fc80 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1fc90 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
1fca0 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
1fcb0 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1fcc0 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
1fcd0 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
1fce0 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
1fcf0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1fd00 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1fd10 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69  X,N) and the pri
1fd20 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1fd30 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73   freed..** ^If s
1fd40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1fd50 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,N) returns NULL
1fd60 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69   and N is positi
1fd70 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  ve, then the.** 
1fd80 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1fd90 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a   is not freed..*
1fda0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1fdb0 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29  3_realloc64(X,N)
1fdc0 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b   interfaces work
1fdd0 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a  s the same as.**
1fde0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1fdf0 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61  (X,N) except tha
1fe00 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20  t N is a 64-bit 
1fe10 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
1fe20 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
1fe30 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
1fe40 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nteger..**.** ^I
1fe50 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20  f X is a memory 
1fe60 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69  allocation previ
1fe70 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
1fe80 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1fe90 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
1fea0 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c  _malloc64(), sql
1feb0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20  ite3_realloc(), 
1fec0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1fed0 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20  oc64(), then.** 
1fee0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1fef0 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a   returns the siz
1ff00 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79  e of that memory
1ff10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62   allocation in b
1ff20 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61  ytes..** ^The va
1ff30 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1ff40 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
1ff50 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72   might be larger
1ff60 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72   than the number
1ff70 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71  .** of bytes req
1ff80 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61  uested when X wa
1ff90 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49  s allocated.  ^I
1ffa0 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f X is a NULL po
1ffb0 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71  inter then.** sq
1ffc0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
1ffd0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66  eturns zero.  If
1ffe0 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d   X points to som
1fff0 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e  ething that is n
20000 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e  ot.** the beginn
20010 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ing of memory al
20020 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20  location, or if 
20030 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66  it points to a f
20040 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64  ormerly.** valid
20050 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
20060 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20  on that has now 
20070 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e  been freed, then
20080 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
20090 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   of sqlite3_msiz
200a0 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65  e(X) is undefine
200b0 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68  d and possibly h
200c0 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  armful..**.** ^T
200d0 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e  he memory return
200e0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ed by sqlite3_ma
200f0 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f  lloc(), sqlite3_
20100 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  realloc(),.** sq
20110 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
20120 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
20130 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20  alloc64().** is 
20140 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
20150 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
20160 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
20170 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
20180 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
20190 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
201a0 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
201b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
201c0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
201d0 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
201e0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
201f0 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
20200 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
20210 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
20220 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
20230 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
20240 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
20250 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
20260 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
20270 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
20280 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
20290 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
202a0 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
202b0 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
202c0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
202d0 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
202e0 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  d..**.** Prior t
202f0 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
20300 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e   3.7.10, the Win
20310 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
20320 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a  e layer called.*
20330 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
20340 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
20350 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
20360 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
20370 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
20380 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
20390 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
203a0 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
203b0 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
203c0 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
203d0 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
203e0 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
203f0 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
20400 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
20410 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62  were detected, b
20420 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20  ut.** they were 
20430 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
20440 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
20450 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
20460 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
20470 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
20480 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
20490 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
204a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
204b0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
204c0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
204d0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
204e0 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
204f0 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
20500 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
20510 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
20520 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
20530 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
20540 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
20550 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
20560 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
20570 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
20580 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
20590 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
205a0 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
205b0 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
205c0 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
205d0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
205e0 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
205f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20600 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
20610 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
20620 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
20630 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33  malloc64(sqlite3
20640 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a  _uint64);.void *
20650 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20660 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69  void*, int);.voi
20670 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
20680 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69  oc64(void*, sqli
20690 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
206a0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76  d sqlite3_free(v
206b0 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75  oid*);.sqlite3_u
206c0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73  int64 sqlite3_ms
206d0 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ize(void*);../*.
206e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
206f0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
20700 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
20710 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
20720 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
20730 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
20740 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
20750 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
20760 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
20770 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
20780 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
20790 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
207a0 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
207b0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
207c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
207d0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
207e0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
207f0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
20800 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
20810 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
20820 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
20830 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
20840 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
20850 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
20860 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
20870 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
20880 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
20890 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
208a0 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
208b0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
208c0 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
208d0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
208e0 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
208f0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
20900 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
20910 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
20920 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
20930 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
20940 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
20950 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
20960 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
20970 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
20980 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
20990 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
209a0 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
209b0 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
209c0 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
209d0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
209e0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
209f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
20a00 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
20a10 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
20a20 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
20a30 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
20a40 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
20a50 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
20a60 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
20a70 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
20a80 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
20a90 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
20aa0 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
20ab0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
20ac0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
20ad0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
20ae0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
20af0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
20b00 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
20b10 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
20b20 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
20b30 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
20b40 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
20b50 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
20b60 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
20b70 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
20b80 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
20b90 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
20ba0 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
20bb0 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
20bc0 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
20bd0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
20be0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
20bf0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
20c00 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
20c10 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
20c20 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
20c30 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
20c40 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
20c50 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
20c60 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
20c70 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
20c80 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
20c90 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
20ca0 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
20cb0 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
20cc0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
20cd0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
20ce0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
20cf0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
20d00 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
20d10 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
20d20 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
20d30 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
20d40 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
20d50 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
20d60 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65  uffer P..** ^The
20d70 20 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e   P parameter can
20d80 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
20d90 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  er..**.** ^If th
20da0 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e  is routine has n
20db0 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73  ot been previous
20dc0 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20  ly called or if 
20dd0 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20  the previous.** 
20de0 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20  call had N less 
20df0 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55  than one or a NU
20e00 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50  LL pointer for P
20e10 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20  , then the PRNG 
20e20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69  is.** seeded usi
20e30 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
20e40 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  tained from the 
20e50 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
20e60 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66  od of.** the def
20e70 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
20e80 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49  s] object..** ^I
20e90 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
20ea0 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
20eb0 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20  ine had an N of 
20ec0 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a  1 or more and a.
20ed0 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68  ** non-NULL P th
20ee0 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  en the pseudo-ra
20ef0 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
20f00 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
20f10 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
20f20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
20f30 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
20f40 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
20f50 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  hod..*/.void sql
20f60 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
20f70 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
20f80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20f90 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
20fa0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
20fb0 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
20fc0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59  : sqlite3.** KEY
20fd0 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a  WORDS: {authoriz
20fe0 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a  er callback}.**.
20ff0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
21000 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
21010 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21020 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
21030 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
21040 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
21050 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
21060 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
21070 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
21080 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
21090 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
210a0 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
210b0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
210c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
210d0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
210e0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
210f0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
21100 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21110 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v3()], [sqlite3_
21120 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73  prepare16()], [s
21130 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
21140 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  _v2()],.** and [
21150 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
21160 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v3()].  ^At va
21170 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
21180 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
21190 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
211a0 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
211b0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
211c0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
211d0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
211e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
211f0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
21200 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
21210 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
21220 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
21230 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
21240 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
21250 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
21260 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
21270 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
21280 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
21290 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
212a0 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
212b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
212c0 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
212d0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
212e0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
212f0 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
21300 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
21310 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
21320 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
21330 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
21340 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
21350 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
21360 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
21370 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
21380 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
21390 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
213a0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
213b0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
213c0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
213d0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
213e0 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
213f0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
21400 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
21410 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
21420 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
21430 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
21440 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
21450 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
21460 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
21470 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
21480 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
21490 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
214a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
214b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
214c0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
214d0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
214e0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
214f0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
21500 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
21510 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
21520 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
21530 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
21540 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
21550 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21560 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
21570 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
21580 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
21590 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
215a0 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
215b0 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
215c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
215d0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
215e0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
215f0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
21600 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
21610 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
21620 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
21630 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
21640 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
21650 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
21660 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
21670 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
21680 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e  either NULL poin
21690 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72  ters or zero-ter
216a0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a  minated strings.
216b0 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20  ** that contain 
216c0 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69  additional detai
216d0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
216e0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
216f0 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  ized..** Applica
21700 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79  tions must alway
21710 73 20 62 65 20 70 72 65 70 61 72 65 64 20 74 6f  s be prepared to
21720 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c   encounter a NUL
21730 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79  L pointer in any
21740 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64  .** of the third
21750 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 69 78   through the six
21760 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  th parameters of
21770 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69   the authorizati
21780 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
21790 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
217a0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
217b0 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
217c0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
217d0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
217e0 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
217f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21800 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
21810 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
21820 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
21830 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
21840 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
21850 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
21860 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
21870 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
21880 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
21890 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
218a0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
218b0 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
218c0 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
218d0 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
218e0 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
218f0 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
21900 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65  a table..** ^Whe
21910 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72 65 66  n a table is ref
21920 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45  erenced by a [SE
21930 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c  LECT] but no col
21940 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a  umn values are.*
21950 2a 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  * extracted from
21960 20 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72   that table (for
21970 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75   example in a qu
21980 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c  ery like.** "SEL
21990 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f  ECT count(*) FRO
219a0 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74 68 65  M tab") then the
219b0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61   [SQLITE_READ] a
219c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
219d0 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  ck.** is invoked
219e0 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74   once for that t
219f0 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75  able with a colu
21a00 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20  mn name that is 
21a10 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
21a20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
21a30 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
21a40 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
21a50 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
21a60 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
21a70 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
21a80 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
21a90 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
21aa0 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
21ab0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
21ac0 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
21ad0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
21ae0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
21af0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
21b00 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
21b10 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
21b20 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
21b30 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
21b40 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
21b50 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
21b60 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
21b70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
21b80 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
21b90 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
21ba0 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
21bb0 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
21bc0 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
21bd0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
21be0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
21bf0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
21c00 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
21c10 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
21c20 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
21c30 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
21c40 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
21c50 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
21c60 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
21c70 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
21c80 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
21c90 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
21ca0 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
21cb0 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
21cc0 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
21cd0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
21ce0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
21cf0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
21d00 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
21d10 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
21d20 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
21d30 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
21d40 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
21d50 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
21d60 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
21d70 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
21d80 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
21d90 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
21da0 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
21db0 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
21dc0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
21dd0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
21de0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
21df0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
21e00 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
21e10 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
21e20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
21e30 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
21e40 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
21e50 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
21e60 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
21e70 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
21e80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
21e90 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
21ea0 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
21eb0 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
21ec0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
21ed0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
21ee0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
21ef0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
21f00 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
21f10 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
21f20 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
21f30 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
21f40 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
21f50 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
21f60 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
21f70 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
21f80 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
21f90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21fa0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
21fb0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
21fc0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
21fd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21fe0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
21ff0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
22000 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
22010 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
22020 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
22030 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22040 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
22050 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
22060 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
22070 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
22080 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
22090 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
220a0 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
220b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
220c0 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
220d0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
220e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
220f0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
22100 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
22110 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
22120 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
22130 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
22140 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
22150 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
22160 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
22170 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
22180 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
22190 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
221a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
221b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
221c0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
221d0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
221e0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
221f0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
22200 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
22210 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
22220 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
22230 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
22240 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
22250 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
22260 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
22270 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
22280 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
22290 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
222a0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
222b0 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
222c0 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
222d0 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
222e0 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
222f0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
22300 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
22310 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
22320 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
22330 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
22340 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
22350 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
22360 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
22370 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
22380 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
22390 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
223a0 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
223b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
223c0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
223d0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
223e0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
223f0 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
22400 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
22410 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
22420 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
22430 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
22440 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
22450 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
22460 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
22470 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
22480 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
22490 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
224a0 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
224b0 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
224c0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
224d0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
224e0 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
224f0 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
22500 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74  d as a [conflict
22510 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65   resolution mode
22520 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72  ].** returned fr
22530 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
22540 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
22550 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
22560 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22570 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
22580 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
22590 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
225a0 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
225b0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
225c0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
225d0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
225e0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
225f0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
22600 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
22610 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
22620 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
22630 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
22640 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
22650 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
22660 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
22670 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
22680 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
22690 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
226a0 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
226b0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
226c0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
226d0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
226e0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
226f0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
22700 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
22710 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
22720 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
22730 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
22740 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
22750 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22760 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
22770 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
22780 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
22790 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
227a0 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
227b0 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
227c0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
227d0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
227e0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
227f0 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
22800 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
22810 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
22820 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
22830 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
22840 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
22850 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
22860 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
22870 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
22880 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
22890 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
228a0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
228b0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
228c0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
228d0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
228e0 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
228f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
22900 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
22910 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
22920 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
22930 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
22940 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
22950 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
22960 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
22970 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
22980 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
22990 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
229a0 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
229b0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
229c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
229d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
229e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
229f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
22a00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
22a10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
22a20 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
22a30 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
22a40 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
22a50 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22a60 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22a70 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
22a80 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
22a90 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22aa0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22ab0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22ac0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
22ad0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
22ae0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
22af0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22b00 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22b10 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
22b20 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22b30 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22b40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22b50 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
22b60 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
22b70 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
22b80 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
22b90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22ba0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
22bb0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
22bc0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
22bd0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22be0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22bf0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
22c00 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
22c10 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
22c20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22c30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22c40 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
22c50 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
22c60 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22c70 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22c80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22c90 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
22ca0 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
22cb0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22cc0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22cd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22ce0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
22cf0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
22d00 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
22d10 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22d20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22d30 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
22d40 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
22d50 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22d60 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22d70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22d80 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
22d90 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
22da0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
22db0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22dc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22dd0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
22de0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
22df0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
22e00 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22e10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22e20 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
22e30 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
22e40 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
22e50 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22e60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22e70 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
22e80 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
22e90 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
22ea0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22eb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22ec0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
22ed0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
22ee0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
22ef0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
22f00 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22f10 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
22f20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
22f30 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
22f40 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22f50 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
22f60 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
22f70 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
22f80 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22f90 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22fa0 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
22fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
22fc0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
22fd0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
22fe0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
22ff0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
23000 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
23010 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
23020 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
23030 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
23040 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
23050 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
23060 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
23070 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
23080 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23090 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
230a0 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
230b0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
230c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
230d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
230e0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
230f0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
23100 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
23110 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
23120 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23130 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
23140 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
23150 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
23160 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23170 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23180 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
23190 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
231a0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
231b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
231c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
231d0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
231e0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
231f0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
23200 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23210 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23220 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
23230 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
23240 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
23250 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23260 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23270 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
23280 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
23290 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
232a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
232b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
232c0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
232d0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
232e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
232f0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
23300 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23310 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
23320 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
23330 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
23340 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
23350 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
23360 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
23370 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
23380 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
23390 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
233a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
233b0 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
233c0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
233d0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
233e0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
233f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
23400 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23410 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
23420 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
23430 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53  ne SQLITE_RECURS
23440 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33  IVE            3
23450 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  3   /* NULL     
23460 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
23470 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a         */../*.**
23480 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
23490 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
234a0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45   Functions.** ME
234b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
234c0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
234d0 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74 65  es are deprecate
234e0 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69  d. Use the [sqli
234f0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
23500 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73  interface.** ins
23510 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74  tead of the rout
23520 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 68  ines described h
23530 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ere..**.** These
23540 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
23550 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
23560 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
23570 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
23580 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
23590 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
235a0 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
235b0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
235c0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
235d0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
235e0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
235f0 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
23600 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
23610 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
23620 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
23630 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
23640 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
23650 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
23660 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
23670 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
23680 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
23690 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
236a0 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
236b0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
236c0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
236d0 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
236e0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
236f0 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
23700 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
23710 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
23720 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
23730 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
23740 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
23750 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
23760 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
23770 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
23780 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
23790 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52  * The [SQLITE_TR
237a0 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
237b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
237c0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
237d0 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20  to limit.** the 
237e0 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64  length of [bound
237f0 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61   parameter] expa
23800 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74  nsion in the out
23810 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74  put of sqlite3_t
23820 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  race()..**.** ^T
23830 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
23840 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
23850 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  by sqlite3_profi
23860 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  le() is invoked.
23870 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73  ** as each SQL s
23880 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
23890 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  s.  ^The profile
238a0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
238b0 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  ns.** the origin
238c0 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  al statement tex
238d0 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74  t and an estimat
238e0 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20  e of wall-clock 
238f0 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c  time.** of how l
23900 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65  ong that stateme
23910 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20  nt took to run. 
23920 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
23930 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69  llback.** time i
23940 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61  s in units of na
23950 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76  noseconds, howev
23960 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  er the current i
23970 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
23980 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65   is only capable
23990 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20   of millisecond 
239a0 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68  resolution so th
239b0 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e  e six least sign
239c0 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74  ificant.** digit
239d0 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72  s in the time ar
239e0 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20  e meaningless.  
239f0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
23a00 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67  of SQLite.** mig
23a10 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74  ht provide great
23a20 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e  er resolution on
23a30 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61   the profiler ca
23a40 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20  llback.  The.** 
23a50 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
23a60 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f  ) function is co
23a70 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d  nsidered experim
23a80 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20  ental and is.** 
23a90 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
23aa0 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  e in future vers
23ab0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
23ac0 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  */.SQLITE_DEPREC
23ad0 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74  ATED void *sqlit
23ae0 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
23af0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61  *,.   void(*xTra
23b00 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
23b10 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
23b20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
23b30 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  D void *sqlite3_
23b40 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
23b50 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
23b60 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
23b70 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
23b80 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
23b90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23ba0 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74   SQL Trace Event
23bb0 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
23bc0 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45  DS: SQLITE_TRACE
23bd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
23be0 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20  stants identify 
23bf0 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74  classes of event
23c00 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f  s that can be mo
23c10 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67  nitored.** using
23c20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72   the [sqlite3_tr
23c30 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e  ace_v2()] tracin
23c40 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 4d 20  g logic.  The M 
23c50 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
23c60 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
23c70 28 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 20 61 6e  (D,M,X,P)] is an
23c80 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69   OR-ed combinati
23c90 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  on of one or mor
23ca0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
23cb0 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
23cc0 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67    ^The first arg
23cd0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61  ument to the tra
23ce0 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  ce callback.** i
23cf0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  s one of the fol
23d00 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
23d10 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63  ..**.** New trac
23d20 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ing constants ma
23d30 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
23d40 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
23d50 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61  *.** ^A trace ca
23d60 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20  llback has four 
23d70 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c  arguments: xCall
23d80 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
23d90 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
23da0 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
23db0 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64  integer type cod
23dc0 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68  es above..** ^Th
23dd0 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
23de0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
23df0 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61  ntext pointer pa
23e00 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
23e10 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  * fourth argumen
23e20 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  t to [sqlite3_tr
23e30 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68  ace_v2()]..** Th
23e40 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
23e50 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
23e60 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
23e70 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
23e80 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
23e90 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d  ITE_TRACE_STMT]]
23ea0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
23eb0 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_STMT</dt>.** <
23ec0 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
23ed0 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63  ACE_STMT callbac
23ee0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
23ef0 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  n a prepared sta
23f00 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20  tement.** first 
23f10 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61  begins running a
23f20 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f  nd possibly at o
23f30 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e  ther times durin
23f40 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69  g the.** executi
23f50 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  on of the prepar
23f60 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75  ed statement, su
23f70 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61  ch as at the sta
23f80 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72  rt of each.** tr
23f90 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d  igger subprogram
23fa0 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  . ^The P argumen
23fb0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
23fc0 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  o the.** [prepar
23fd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
23fe0 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  The X argument i
23ff0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
24000 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a   string which.**
24010 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64   is the unexpand
24020 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74  ed SQL text of t
24030 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
24040 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20  ement or an SQL 
24050 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74  comment .** that
24060 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69   indicates the i
24070 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74  nvocation of a t
24080 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61  rigger.  ^The ca
24090 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75  llback can compu
240a0 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74  te.** the same t
240b0 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68  ext that would h
240c0 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65  ave been returne
240d0 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20  d by the legacy 
240e0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
240f0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62  ].** interface b
24100 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72  y using the X ar
24110 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65  gument when X be
24120 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61  gins with "--" a
24130 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b  nd invoking.** [
24140 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
24150 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69  _sql(P)] otherwi
24160 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  se..**.** [[SQLI
24170 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
24180 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
24190 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e  ACE_PROFILE</dt>
241a0 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
241b0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
241c0 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64   callback provid
241d0 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  es approximately
241e0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66   the same.** inf
241f0 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70  ormation as is p
24200 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b  rovided by the [
24210 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
24220 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  )] callback..** 
24230 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
24240 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
24250 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
24260 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
24270 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70  .** X argument p
24280 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69  oints to a 64-bi
24290 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  t integer which 
242a0 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64  is the estimated
242b0 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   of.** the numbe
242c0 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20  r of nanosecond 
242d0 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
242e0 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  d statement took
242f0 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65   to run..** ^The
24300 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52   SQLITE_TRACE_PR
24310 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69  OFILE callback i
24320 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
24330 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  he statement fin
24340 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ishes..**.** [[S
24350 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d  QLITE_TRACE_ROW]
24360 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
24370 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c  CE_ROW</dt>.** <
24380 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
24390 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b  ACE_ROW callback
243a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
243b0 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a  ever a prepared.
243c0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e  ** statement gen
243d0 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20  erates a single 
243e0 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20  row of result.  
243f0 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d  .** ^The P argum
24400 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
24410 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
24420 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
24430 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65   the.** X argume
24440 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a  nt is unused..**
24450 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
24460 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53  CE_CLOSE]] <dt>S
24470 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
24480 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
24490 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  n SQLITE_TRACE_C
244a0 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  LOSE callback is
244b0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
244c0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
244d0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a  ection closes..*
244e0 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
244f0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
24500 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
24510 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65  connection] obje
24520 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20  ct.** and the X 
24530 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
24540 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ed..** </dl>.*/.
24550 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
24560 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20  RACE_STMT       
24570 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x01.#define SQL
24580 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
24590 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e  E    0x02.#defin
245a0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  e SQLITE_TRACE_R
245b0 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23  OW        0x04.#
245c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
245d0 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30  ACE_CLOSE      0
245e0 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  x08../*.** CAPI3
245f0 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48  REF: SQL Trace H
24600 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ook.** METHOD: s
24610 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
24620 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  e sqlite3_trace_
24630 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65  v2(D,M,X,P) inte
24640 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
24650 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  a trace callback
24660 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61  .** function X a
24670 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65  gainst [database
24680 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
24690 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d  using property m
246a0 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e  ask M.** and con
246b0 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20  text pointer P. 
246c0 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62   ^If the X callb
246d0 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f  ack is.** NULL o
246e0 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20  r if the M mask 
246f0 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72  is zero, then tr
24700 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65  acing is disable
24710 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67  d.  The.** M arg
24720 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
24730 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65  the bitwise OR-e
24740 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
24750 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  .** zero or more
24760 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20   [SQLITE_TRACE] 
24770 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
24780 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65   ^Each call to e
24790 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72  ither sqlite3_tr
247a0 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
247b0 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72  _trace_v2() over
247c0 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65  rides .** (cance
247d0 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61  ls) any prior ca
247e0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74  lls to sqlite3_t
247f0 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
24800 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a  3_trace_v2()..**
24810 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62  .** ^The X callb
24820 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
24830 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74  henever any of t
24840 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69  he events identi
24850 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b  fied by .** mask
24860 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20   M occur.  ^The 
24870 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76  integer return v
24880 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61  alue from the ca
24890 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e  llback is curren
248a0 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20  tly.** ignored, 
248b0 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20  though this may 
248c0 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
248d0 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c   releases.  Call
248e0 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  back.** implemen
248f0 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72  tations should r
24900 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e  eturn zero to en
24910 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70  sure future comp
24920 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
24930 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
24940 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
24950 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74  th four argument
24960 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c  s: callback(T,C,
24970 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20  P,X)..** ^The T 
24980 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
24990 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
249a0 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e  RACE].** constan
249b0 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77  ts to indicate w
249c0 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  hy the callback 
249d0 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20  was invoked..** 
249e0 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20  ^The C argument 
249f0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
24a00 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
24a10 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58  ..** The P and X
24a20 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70   arguments are p
24a30 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65  ointers whose me
24a40 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e  anings depend on
24a50 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71   T..**.** The sq
24a60 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
24a70 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
24a80 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63  tended to replac
24a90 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  e the legacy.** 
24aa0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
24ab0 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64  te3_trace()] and
24ac0 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
24ad0 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68  e()], both of wh
24ae0 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65  ich.** are depre
24af0 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  cated..*/.int sq
24b00 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a  lite3_trace_v2(.
24b10 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e    sqlite3*,.  un
24b20 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20  signed uMask,.  
24b30 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28  int(*xCallback)(
24b40 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76  unsigned,void*,v
24b50 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76  oid*,void*),.  v
24b60 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a  oid *pCtx.);../*
24b70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
24b80 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
24b90 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
24ba0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
24bb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
24bc0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
24bd0 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
24be0 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
24bf0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
24c00 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
24c10 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
24c20 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
24c30 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
24c40 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
24c50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24c60 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
24c70 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
24c80 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
24c90 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
24ca0 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
24cb0 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
24cc0 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
24cd0 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
24ce0 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
24cf0 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
24d00 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
24d10 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
24d20 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
24d30 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
24d40 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
24d50 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
24d60 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
24d70 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
24d80 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
24d90 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
24da0 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
24db0 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
24dc0 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
24dd0 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
24de0 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
24df0 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
24e00 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
24e10 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
24e20 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
24e30 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
24e40 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
24e50 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
24e60 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
24e70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24e80 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
24e90 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
24ea0 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
24eb0 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
24ec0 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
24ed0 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
24ee0 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
24ef0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
24f00 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
24f10 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
24f20 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
24f30 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
24f40 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
24f50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
24f60 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
24f70 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
24f80 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
24f90 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
24fa0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
24fb0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
24fc0 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
24fd0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
24fe0 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
24ff0 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
25000 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
25010 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
25020 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
25030 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
25040 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
25050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
25060 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
25070 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
25080 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
25090 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
250a0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
250b0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
250c0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
250d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
250e0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
250f0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
25100 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
25110 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
25120 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
25130 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
25140 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
25150 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
25160 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25170 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
25180 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
25190 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  n.** CONSTRUCTOR
251a0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
251b0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
251c0 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
251d0 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
251e0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
251f0 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
25200 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
25210 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
25220 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
25230 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
25240 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
25250 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25260 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
25270 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
25280 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
25290 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
252a0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
252b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
252c0 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
252d0 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
252e0 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
252f0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
25300 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
25310 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
25320 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
25330 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
25340 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
25350 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
25360 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
25370 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
25380 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
25390 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
253a0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
253b0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
253c0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
253d0 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
253e0 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
253f0 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
25400 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
25410 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
25420 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
25430 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
25440 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
25450 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
25460 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
25470 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
25480 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
25490 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
254a0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
254b0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
254c0 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
254d0 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
254e0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
254f0 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
25500 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
25510 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c  lt encoding will
25520 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61   be UTF-8 for da
25530 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20  tabases created 
25540 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  using.** sqlite3
25550 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
25560 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e  e3_open_v2().  ^
25570 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
25580 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73  ding for databas
25590 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73  es.** created us
255a0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
255b0 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46  16() will be UTF
255c0 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
255d0 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
255e0 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
255f0 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
25600 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
25610 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
25620 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
25630 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
25640 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
25650 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
25660 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
25670 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
25680 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
25690 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
256a0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
256b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
256c0 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
256d0 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
256e0 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
256f0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
25700 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
25710 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
25720 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
25730 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
25740 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
25750 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
25760 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
25770 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
25780 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
25790 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
257a0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
257b0 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
257c0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
257d0 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
257e0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
257f0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
25800 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
25810 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
25820 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
25830 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
25840 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
25850 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
25860 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
25870 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
25880 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
25890 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
258a0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
258b0 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
258c0 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
258d0 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
258e0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
258f0 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
25900 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
25910 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
25920 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
25930 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
25940 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
25950 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
25960 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
25970 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
25980 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
25990 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
259a0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
259b0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
259c0 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
259d0 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
259e0 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
259f0 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
25a00 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
25a10 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
25a20 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
25a30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
25a40 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
25a50 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
25a60 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
25a70 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
25a80 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
25a90 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
25aa0 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
25ab0 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
25ac0 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
25ad0 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
25ae0 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
25af0 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
25b00 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
25b10 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
25b20 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
25b30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
25b40 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
25b50 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
25b60 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
25b70 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
25b80 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
25b90 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
25ba0 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
25bb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
25bc0 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
25bd0 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
25be0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
25bf0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
25c00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
25c10 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
25c20 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
25c30 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
25c40 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
25c50 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
25c60 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
25c70 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
25c80 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
25c90 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
25ca0 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
25cb0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
25cc0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
25cd0 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
25ce0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
25cf0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
25d00 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
25d10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
25d20 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
25d30 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
25d40 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
25d50 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
25d60 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
25d70 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
25d80 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
25d90 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
25da0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
25db0 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
25dc0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
25dd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
25de0 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
25df0 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
25e00 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
25e10 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
25e20 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
25e30 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
25e40 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
25e50 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
25e60 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
25e70 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
25e80 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
25e90 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
25ea0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25eb0 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
25ec0 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
25ed0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
25ee0 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
25ef0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
25f00 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
25f10 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
25f20 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
25f30 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
25f40 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
25f50 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
25f60 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
25f70 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
25f80 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
25f90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25fa0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
25fb0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
25fc0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
25fd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
25fe0 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
25ff0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
26000 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
26010 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
26020 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
26030 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
26040 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
26050 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
26060 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
26070 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
26080 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
26090 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
260a0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
260b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
260c0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
260d0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
260e0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
260f0 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
26100 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
26110 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
26120 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
26130 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
26140 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
26150 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
26160 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
26170 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
26180 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
26190 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
261a0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
261b0 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
261c0 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
261d0 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
261e0 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
261f0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
26200 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
26210 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
26220 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
26230 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
26240 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
26250 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
26260 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
26270 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
26280 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
26290 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
262a0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
262b0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
262c0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
262d0 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
262e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
262f0 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
26300 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
26310 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
26320 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
26330 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
26340 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
26350 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
26360 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
26370 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
26380 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
26390 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
263a0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
263b0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
263c0 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
263d0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
263e0 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
263f0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
26400 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
26410 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
26420 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
26430 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
26440 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
26450 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
26460 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
26470 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
26480 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
26490 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
264a0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
264b0 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66 69  ption..** URI fi
264c0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
264d0 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
264e0 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
264f0 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
26500 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
26510 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
26520 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
26530 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
26540 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
26550 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
26560 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
26570 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
26580 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
26590 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
265a0 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
265b0 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
265c0 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
265d0 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
265e0 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
265f0 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
26600 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
26610 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
26620 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
26630 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
26640 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
26650 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
26660 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
26670 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
26680 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
26690 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
266a0 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
266b0 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
266c0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
266d0 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
266e0 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
266f0 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
26700 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
26710 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
26720 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
26730 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
26740 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
26750 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
26760 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
26770 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
26780 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
26790 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
267a0 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
267b0 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
267c0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
267d0 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
267e0 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
267f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
26800 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
26810 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
26820 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e  th. .** ^(On win
26830 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
26840 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
26850 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
26860 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
26870 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
26880 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20   "C:").)^.**.** 
26890 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
268a0 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
268b0 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
268c0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
268d0 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
268e0 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
268f0 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
26900 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
26910 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
26920 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
26930 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
26940 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69  .** SQLite and i
26950 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53  ts built-in [VFS
26960 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68  es] interpret th
26970 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71  e.** following q
26980 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
26990 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
269a0 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
269b0 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
269c0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
269d0 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
269e0 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
269f0 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
26a00 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
26a10 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
26a20 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
26a30 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
26a40 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
26a50 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
26a60 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
26a70 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
26a80 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
26a90 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
26aa0 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
26ab0 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
26ac0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
26ad0 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
26ae0 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
26af0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26b00 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
26b10 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
26b20 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
26b30 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
26b40 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
26b50 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
26b60 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
26b70 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
26b80 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
26b90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
26ba0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
26bb0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
26bc0 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
26bd0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
26be0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
26bf0 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
26c00 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
26c10 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
26c20 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
26c30 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
26c40 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
26c50 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
26c60 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
26c70 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
26c80 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
26c90 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
26ca0 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
26cb0 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
26cc0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
26cd0 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
26ce0 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
26cf0 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
26d00 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
26d10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
26d20 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
26d30 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
26d40 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
26d50 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
26d60 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
26d70 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
26d80 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
26d90 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
26da0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
26db0 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
26dc0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
26dd0 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
26de0 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
26df0 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
26e00 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
26e10 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
26e20 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
26e30 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
26e40 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
26e50 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
26e60 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
26e70 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
26e80 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
26e90 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
26ea0 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
26eb0 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
26ec0 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
26ed0 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
26ee0 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
26ef0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
26f00 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
26f10 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
26f20 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
26f30 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
26f40 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
26f50 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
26f60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
26f70 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
26f80 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
26f90 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
26fa0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
26fb0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
26fc0 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
26fd0 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
26fe0 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
26ff0 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
27000 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
27010 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
27020 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
27030 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
27040 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
27050 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
27060 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
27070 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
27080 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
27090 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
270a0 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
270b0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
270c0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
270d0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
270e0 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
270f0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
27100 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
27110 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
27120 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
27130 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
27140 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
27150 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
27160 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65  ehavior requeste
27170 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
27180 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
27190 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
271a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
271b0 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
271c0 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f  .**  <li> <b>pso
271d0 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77  w</b>: ^The psow
271e0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63   parameter indic
271f0 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20  ates whether or 
27200 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b  not the.**     [
27210 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72  powersafe overwr
27220 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f  ite] property do
27230 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61  es or does not a
27240 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20  pply to the.**  
27250 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61     storage media
27260 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61   on which the da
27270 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69  tabase file resi
27280 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  des..**.**  <li>
27290 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20   <b>nolock</b>: 
272a0 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61  ^The nolock para
272b0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
272c0 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  an query paramet
272d0 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20  er.**     which 
272e0 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20  if set disables 
272f0 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20  file locking in 
27300 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
27310 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a   modes.  This.**
27320 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66       is useful f
27330 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64  or accessing a d
27340 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c  atabase on a fil
27350 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65  esystem that doe
27360 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70  s not.**     sup
27370 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43  port locking.  C
27380 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73  aution:  Databas
27390 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67  e corruption mig
273a0 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f  ht result if two
273b0 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20  .**     or more 
273c0 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20  processes write 
273d0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
273e0 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65  base and any one
273f0 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20   of those.**    
27400 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20   processes uses 
27410 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20  nolock=1..**.** 
27420 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62   <li> <b>immutab
27430 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d  le</b>: ^The imm
27440 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72  utable parameter
27450 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
27460 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  ery.**     param
27470 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61  eter that indica
27480 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74  tes that the dat
27490 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74  abase file is st
274a0 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72  ored on.**     r
274b0 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20  ead-only media. 
274c0 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65   ^When immutable
274d0 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20   is set, SQLite 
274e0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
274f0 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65  .**     database
27500 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
27510 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79  changed, even by
27520 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20   a process with 
27530 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72  higher.**     pr
27540 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20  ivilege, and so 
27550 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
27560 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79  opened read-only
27570 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67   and all locking
27580 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e  .**     and chan
27590 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20  ge detection is 
275a0 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69  disabled.  Cauti
275b0 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20  on: Setting the 
275c0 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20  immutable.**    
275d0 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64   property on a d
275e0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61  atabase file tha
275f0 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63  t does in fact c
27600 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74  hange can result
27610 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72  .**     in incor
27620 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c  rect query resul
27630 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ts and/or [SQLIT
27640 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72  E_CORRUPT] error
27650 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c  s..**     See al
27660 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  so: [SQLITE_IOCA
27670 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a  P_IMMUTABLE]..**
27680 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e         .** </ul>
27690 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
276a0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
276b0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
276c0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
276d0 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
276e0 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
276f0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
27700 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
27710 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
27720 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
27730 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
27740 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
27750 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
27760 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
27770 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
27780 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
27790 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
277a0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
277b0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
277c0 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
277d0 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
277e0 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
277f0 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
27800 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
27810 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
27820 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
27830 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
27840 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
27850 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
27860 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
27870 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
27880 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
27890 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
278a0 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
278b0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
278c0 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
278d0 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
278e0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
278f0 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
27900 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
27910 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
27920 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
27930 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
27940 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
27950 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
27960 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
27970 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
27980 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
27990 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
279a0 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
279b0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
279c0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
279d0 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
279e0 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
279f0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
27a00 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
27a10 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
27a20 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
27a30 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
27a40 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
27a50 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
27a60 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
27a70 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
27a80 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
27a90 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
27aa0 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
27ab0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
27ac0 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
27ad0 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
27ae0 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
27af0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
27b00 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
27b10 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
27b20 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
27b30 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
27b40 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
27b50 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
27b60 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
27b70 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
27b80 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
27b90 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
27ba0 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
27bb0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
27bc0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
27bd0 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
27be0 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
27bf0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
27c00 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
27c10 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
27c20 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
27c30 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
27c40 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69  b?vfs=unix-dotfi
27c50 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  le <td>.**      
27c60 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
27c70 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
27c80 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
27c90 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f  ial VFS "unix-do
27ca0 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20  tfile".**       
27cb0 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74     that uses dot
27cc0 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20  -files in place 
27cd0 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72  of posix advisor
27ce0 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74  y locking..** <t
27cf0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
27d00 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
27d10 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
27d20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
27d30 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
27d40 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
27d50 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
27d60 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
27d70 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
27d80 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
27d90 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
27da0 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
27db0 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
27dc0 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
27dd0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
27de0 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
27df0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
27e00 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
27e10 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
27e20 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
27e30 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
27e40 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
27e50 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
27e60 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
27e70 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
27e80 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
27e90 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
27ea0 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
27eb0 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
27ec0 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
27ed0 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
27ee0 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
27ef0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
27f00 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
27f10 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
27f20 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
27f30 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
27f40 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
27f50 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
27f60 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
27f70 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
27f80 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
27f90 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
27fa0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
27fb0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
27fc0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
27fd0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
27fe0 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
27ff0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
28000 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
28010 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
28020 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
28030 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
28040 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
28050 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
28060 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
28070 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
28080 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
28090 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
280a0 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
280b0 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
280c0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
280d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
280e0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
280f0 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
28100 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
28110 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
28120 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
28130 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
28140 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
28150 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
28160 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
28170 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
28180 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
28190 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
281a0 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
281b0 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
281c0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
281d0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
281e0 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ory].*/.int sqli
281f0 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73  te3_open(.  cons
28200 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
28210 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
28220 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
28230 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
28240 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
28250 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
28260 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
28270 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
28280 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
28290 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
282a0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
282b0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
282c0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
282d0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
282e0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
282f0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
28300 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
28310 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
28320 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
28330 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
28340 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
28350 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
28360 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
28370 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
28380 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
28390 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
283a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
283b0 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
283c0 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
283d0 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
283e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
283f0 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
28400 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
28410 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
28420 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
28430 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
28440 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
28450 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
28460 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
28470 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
28480 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
28490 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
284a0 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
284b0 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
284c0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
284d0 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
284e0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
284f0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
28500 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
28510 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
28520 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
28530 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
28540 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
28550 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
28560 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
28570 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
28580 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
28590 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
285a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
285b0 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
285c0 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
285d0 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
285e0 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
285f0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
28600 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
28610 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
28620 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
28630 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
28640 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
28650 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
28660 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
28670 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
28680 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
28690 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
286a0 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
286b0 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
286c0 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
286d0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
286e0 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
286f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
28700 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
28710 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
28720 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
28730 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
28740 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
28750 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
28760 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
28770 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
28780 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
28790 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
287a0 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
287b0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
287c0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
287d0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
287e0 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
287f0 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
28800 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
28810 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
28820 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
28830 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
28840 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
28850 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
28860 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
28870 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
28880 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
28890 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
288a0 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
288b0 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
288c0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
288d0 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
288e0 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
288f0 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
28900 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
28910 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
28920 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
28930 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
28940 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
28950 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
28960 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
28970 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
28980 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
28990 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
289a0 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
289b0 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
289c0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
289d0 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
289e0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
289f0 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
28a00 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
28a10 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
28a20 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
28a30 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
28a40 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
28a50 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
28a60 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
28a70 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
28a80 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
28a90 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
28aa0 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
28ab0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
28ac0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
28ad0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
28ae0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
28af0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
28b00 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
28b10 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
28b20 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
28b30 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
28b40 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
28b50 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
28b60 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
28b70 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
28b80 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
28b90 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
28ba0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
28bb0 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
28bc0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
28bd0 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
28be0 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  e..*/.const char
28bf0 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61   *sqlite3_uri_pa
28c00 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68  rameter(const ch
28c10 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63  ar *zFilename, c
28c20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
28c30 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  m);.int sqlite3_
28c40 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
28c50 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
28c60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
28c70 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
28c80 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
28c90 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
28ca0 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
28cb0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
28cc0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
28cd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
28ce0 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
28cf0 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ssages.** METHOD
28d00 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
28d10 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
28d20 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  ent sqlite3_* AP
28d30 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  I call associate
28d40 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61  d with .** [data
28d50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
28d60 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20   D failed, then 
28d70 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63  the sqlite3_errc
28d80 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65  ode(D) interface
28d90 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
28da0 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
28db0 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64  code] or [extend
28dc0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  ed result code] 
28dd0 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20  for that.** API 
28de0 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20  call..** If the 
28df0 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20  most recent API 
28e00 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73  call was success
28e10 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ful,.** then the
28e20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
28e30 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  om sqlite3_errco
28e40 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
28e50 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
28e60 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
28e70 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
28e80 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
28e90 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
28ea0 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
28eb0 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
28ec0 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
28ed0 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
28ee0 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
28ef0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
28f00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28f10 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
28f20 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
28f30 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
28f40 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
28f50 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
28f60 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
28f70 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
28f80 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
28f90 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
28fa0 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
28fb0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
28fc0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
28fd0 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
28fe0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
28ff0 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
29000 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
29010 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
29020 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
29030 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
29040 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
29050 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
29060 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
29070 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
29080 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
29090 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  tions.)^.**.** ^
290a0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73  The sqlite3_errs
290b0 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  tr() interface r
290c0 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69  eturns the Engli
290d0 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74  sh-language text
290e0 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62  .** that describ
290f0 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63  es the [result c
29100 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a  ode], as UTF-8..
29110 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
29120 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
29130 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
29140 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
29150 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e  ly.** and must n
29160 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74  ot be freed by t
29170 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e  he application)^
29180 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
29190 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
291a0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
291b0 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74  in use, it might
291c0 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20   be the.** case 
291d0 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72  that a second er
291e0 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20  ror occurs on a 
291f0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
29200 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  in between.** th
29210 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69  e time of the fi
29220 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68  rst error and th
29230 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20  e call to these 
29240 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57  interfaces..** W
29250 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73  hen that happens
29260 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72  , the second err
29270 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72  or will be repor
29280 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a  ted since these.
29290 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c  ** interfaces al
292a0 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20  ways report the 
292b0 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75  most recent resu
292c0 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a  lt.  To avoid.**
292d0 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65   this, each thre
292e0 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78  ad can obtain ex
292f0 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74  clusive use of t
29300 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
29310 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79  nection] D.** by
29320 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
29330 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28  e3_mutex_enter](
29340 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
29350 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65  x](D)) before be
29360 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73  ginning.** to us
29370 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  e D and invoking
29380 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
29390 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f  leave]([sqlite3_
293a0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66  db_mutex](D)) af
293b0 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73  ter.** all calls
293c0 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63   to the interfac
293d0 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61  es listed here a
293e0 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a  re completed..**
293f0 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66  .** If an interf
29400 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53  ace fails with S
29410 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68  QLITE_MISUSE, th
29420 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74  at means the int
29430 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e  erface.** was in
29440 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c  voked incorrectl
29450 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  y by the applica
29460 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63  tion.  In that c
29470 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f  ase, the.** erro
29480 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61  r code and messa
29490 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f  ge may or may no
294a0 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74  t be set..*/.int
294b0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
294c0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69  (sqlite3 *db);.i
294d0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
294e0 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  ded_errcode(sqli
294f0 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20  te3 *db);.const 
29500 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
29510 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rmsg(sqlite3*);.
29520 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
29530 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c  te3_errmsg16(sql
29540 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68  ite3*);.const ch
29550 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73  ar *sqlite3_errs
29560 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  tr(int);../*.** 
29570 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72  CAPI3REF: Prepar
29580 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
29590 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
295a0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
295b0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
295c0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
295d0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
295e0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
295f0 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
29600 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
29610 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20  hat.** has been 
29620 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69  compiled into bi
29630 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73  nary form and is
29640 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61   ready to be eva
29650 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  luated..**.** Th
29660 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20  ink of each SQL 
29670 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73  statement as a s
29680 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72  eparate computer
29690 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a   program.  The.*
296a0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
296b0 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f  ext is source co
296c0 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20  de.  A prepared 
296d0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
296e0 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70   .** is the comp
296f0 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65  iled object code
29700 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20  .  All SQL must 
29710 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  be converted int
29720 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  o a.** prepared 
29730 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65  statement before
29740 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a   it can be run..
29750 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63  **.** The life-c
29760 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72  ycle of a prepar
29770 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
29780 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73  ect usually goes
29790 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
297a0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
297b0 72 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72  reate the prepar
297c0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
297d0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
297e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
297f0 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76  ..** <li> Bind v
29800 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65  alues to [parame
29810 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
29820 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
29830 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
29840 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
29850 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
29860 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
29870 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
29880 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
29890 52 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  Reset the prepar
298a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
298b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
298c0 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
298d0 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
298e0 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
298f0 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
29900 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
29910 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
29920 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
29930 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
29940 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  >.*/.typedef str
29950 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  uct sqlite3_stmt
29960 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a   sqlite3_stmt;..
29970 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29980 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a  Run-time Limits.
29990 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
299a0 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e3.**.** ^(This 
299b0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
299c0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
299d0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
299e0 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
299f0 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
29a00 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
29a10 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
29a20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
29a30 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
29a40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
29a50 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
29a60 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
29a70 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
29a80 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
29a90 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
29aa0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
29ab0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
29ac0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
29ad0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
29ae0 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
29af0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
29b00 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
29b10 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
29b20 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
29b30 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
29b40 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
29b50 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
29b60 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
29b70 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
29b80 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
29b90 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
29ba0 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
29bb0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
29bc0 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
29bd0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
29be0 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
29bf0 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
29c00 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
29c10 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
29c20 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
29c30 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
29c40 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
29c50 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
29c60 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
29c70 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
29c80 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
29c90 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
29ca0 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
29cb0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
29cc0 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
29cd0 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
29ce0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
29cf0 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
29d00 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
29d10 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
29d20 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
29d30 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
29d40 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
29d50 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
29d60 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
29d70 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
29d80 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
29d90 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
29da0 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
29db0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
29dc0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
29dd0 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
29de0 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
29df0 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
29e00 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
29e10 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
29e20 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
29e30 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
29e40 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
29e50 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
29e60 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
29e70 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
29e80 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
29e90 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
29ea0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
29eb0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
29ec0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
29ed0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
29ee0 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
29ef0 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
29f00 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
29f10 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
29f20 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
29f30 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
29f40 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
29f50 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
29f60 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
29f70 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
29f80 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
29f90 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
29fa0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
29fb0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
29fc0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
29fd0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
29fe0 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
29ff0 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
2a000 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
2a010 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
2a020 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
2a030 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
2a040 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
2a050 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
2a060 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
2a070 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
2a080 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
2a090 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
2a0a0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
2a0b0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
2a0c0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
2a0d0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
2a0e0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
2a0f0 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
2a100 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
2a110 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
2a120 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
2a130 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
2a140 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
2a150 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
2a160 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
2a170 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a180 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
2a190 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
2a1a0 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
2a1b0 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
2a1c0 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
2a1d0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
2a1e0 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
2a1f0 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
2a200 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
2a210 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
2a220 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
2a230 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
2a240 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
2a250 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
2a260 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
2a270 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
2a280 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
2a290 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
2a2a0 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
2a2b0 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
2a2c0 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
2a2d0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
2a2e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2a2f0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
2a300 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
2a310 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a320 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
2a330 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
2a340 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
2a350 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
2a360 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a370 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
2a380 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2a390 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
2a3a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2a3b0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
2a3c0 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
2a3d0 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
2a3e0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a3f0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
2a400 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2a410 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
2a420 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a430 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
2a440 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
2a450 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
2a460 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
2a470 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
2a480 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
2a490 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
2a4a0 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
2a4b0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
2a4c0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
2a4d0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
2a4e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a4f0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
2a500 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2a510 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
2a520 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2a530 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
2a540 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
2a550 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
2a560 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
2a570 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
2a580 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
2a590 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2a5a0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
2a5b0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
2a5c0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2a5d0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
2a5e0 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
2a5f0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
2a600 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2a610 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
2a620 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2a630 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
2a640 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a650 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
2a660 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
2a670 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
2a680 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
2a690 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
2a6a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
2a6b0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   If [sqlite3_pre
2a6c0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  pare_v2()] or.**
2a6d0 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
2a6e0 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74  tries to allocat
2a6f0 65 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65  e space for more
2a700 20 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20   than this many 
2a710 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20  opcodes.** in a 
2a720 73 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20  single prepared 
2a730 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51  statement, an SQ
2a740 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72  LITE_NOMEM error
2a750 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
2a760 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a770 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2a780 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
2a790 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2a7a0 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
2a7b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a7c0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2a7d0 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
2a7e0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
2a7f0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a800 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
2a810 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
2a820 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
2a830 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2a840 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
2a850 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
2a860 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
2a870 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2a880 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
2a890 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
2a8a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a8b0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
2a8c0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
2a8d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
2a8e0 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
2a8f0 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
2a900 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
2a910 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
2a920 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2a930 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2a940 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
2a950 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
2a960 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2a970 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
2a980 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
2a990 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
2a9a0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
2a9b0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2a9c0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
2a9d0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
2a9e0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
2a9f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
2aa00 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
2aa10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2aa20 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
2aa30 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
2aa40 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2aa50 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  [[SQLITE_LIMIT_W
2aa60 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20  ORKER_THREADS]] 
2aa70 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2aa80 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
2aa90 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  S</dt>.** <dd>Th
2aaa0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2aab0 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f   of auxiliary wo
2aac0 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61  rker threads tha
2aad0 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70  t a single.** [p
2aae0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2aaf0 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64  t] may start.</d
2ab00 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
2ab10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ab20 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
2ab30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ab40 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
2ab50 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
2ab60 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
2ab70 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2ab80 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
2ab90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2aba0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2abb0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
2abc0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
2abd0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2abe0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
2abf0 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
2ac00 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2ac10 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
2ac20 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
2ac30 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
2ac40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2ac50 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
2ac60 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
2ac70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
2ac80 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
2ac90 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
2aca0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
2acb0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
2acc0 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
2acd0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
2ace0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
2acf0 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
2ad00 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2ad10 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
2ad20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
2ad30 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2ad40 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20  _WORKER_THREADS 
2ad50 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a            11../*
2ad60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72  .** CAPI3REF: Pr
2ad70 65 70 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a  epare Flags.**.*
2ad80 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
2ad90 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
2ada0 20 66 6c 61 67 73 20 74 68 61 74 20 63 61 6e 20   flags that can 
2adb0 62 65 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a  be passed into.*
2adc0 2a 20 22 70 72 65 70 46 6c 61 67 73 22 20 70 61  * "prepFlags" pa
2add0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 5b  rameter of the [
2ade0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2adf0 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  v3()] and.** [sq
2ae00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2ae10 76 33 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  v3()] interfaces
2ae20 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67  ..**.** New flag
2ae30 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
2ae40 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
2ae50 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
2ae60 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
2ae70 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2ae80 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53  ISTENT]] ^(<dt>S
2ae90 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2aea0 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a  RSISTENT</dt>.**
2aeb0 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f   <dd>The SQLITE_
2aec0 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2aed0 4e 54 20 66 6c 61 67 20 69 73 20 61 20 68 69 6e  NT flag is a hin
2aee0 74 20 74 6f 20 74 68 65 20 71 75 65 72 79 20 70  t to the query p
2aef0 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74  lanner.** that t
2af00 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2af10 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 72 65  ement will be re
2af20 74 61 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e  tained for a lon
2af30 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72  g time and.** pr
2af40 6f 62 61 62 6c 79 20 72 65 75 73 65 64 20 6d 61  obably reused ma
2af50 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74  ny times.)^ ^Wit
2af60 68 6f 75 74 20 74 68 69 73 20 66 6c 61 67 2c 20  hout this flag, 
2af70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2af80 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  _v3()].** and [s
2af90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2afa0 5f 76 33 28 29 5d 20 61 73 73 75 6d 65 20 74 68  _v3()] assume th
2afb0 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  at the prepared 
2afc0 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a  statement will .
2afd0 2a 2a 20 62 65 20 75 73 65 64 20 6a 75 73 74 20  ** be used just 
2afe0 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f 73 74 20  once or at most 
2aff0 61 20 66 65 77 20 74 69 6d 65 73 20 61 6e 64 20  a few times and 
2b000 74 68 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75  then destroyed u
2b010 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2b020 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c  _finalize()] rel
2b030 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68  atively soon. Th
2b040 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
2b050 65 6e 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a  entation acts.**
2b060 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 62 79   on this hint by
2b070 20 61 76 6f 69 64 69 6e 67 20 74 68 65 20 75 73   avoiding the us
2b080 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20  e of [lookaside 
2b090 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f  memory] so as no
2b0a0 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20  t to.** deplete 
2b0b0 74 68 65 20 6c 69 6d 69 74 65 64 20 73 74 6f 72  the limited stor
2b0c0 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  e of lookaside m
2b0d0 65 6d 6f 72 79 2e 20 46 75 74 75 72 65 20 76 65  emory. Future ve
2b0e0 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c  rsions of.** SQL
2b0f0 69 74 65 20 6d 61 79 20 61 63 74 20 6f 6e 20 74  ite may act on t
2b100 68 69 73 20 68 69 6e 74 20 64 69 66 66 65 72 65  his hint differe
2b110 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  ntly..** </dl>.*
2b120 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2b130 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2b140 45 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ENT             
2b150 20 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   0x01../*.** CAP
2b160 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
2b170 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2b180 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
2b190 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
2b1a0 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  mpiler}.** METHO
2b1b0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f  D: sqlite3.** CO
2b1c0 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
2b1d0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f  e3_stmt.**.** To
2b1e0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
2b1f0 73 74 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75  statement, it mu
2b200 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70  st first be comp
2b210 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65  iled into a byte
2b220 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d  -code.** program
2b230 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68   using one of th
2b240 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f  ese routines.  O
2b250 72 2c 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  r, in other word
2b260 73 2c 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  s, these routine
2b270 73 0a 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75  s.** are constru
2b280 63 74 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70  ctors for the [p
2b290 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b2a0 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  t] object..**.**
2b2b0 20 54 68 65 20 70 72 65 66 65 72 72 65 64 20 72   The preferred r
2b2c0 6f 75 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73  outine to use is
2b2d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b2e0 65 5f 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a  e_v2()].  The.**
2b2f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b300 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69  e()] interface i
2b310 73 20 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f  s legacy and sho
2b320 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
2b330 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2b340 61 72 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e  are_v3()] has an
2b350 20 65 78 74 72 61 20 22 70 72 65 70 46 6c 61 67   extra "prepFlag
2b360 73 22 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69  s" option that i
2b370 73 20 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70  s used.** for sp
2b380 65 63 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a  ecial purposes..
2b390 2a 2a 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66  **.** The use of
2b3a0 20 74 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72   the UTF-8 inter
2b3b0 66 61 63 65 73 20 69 73 20 70 72 65 66 65 72 72  faces is preferr
2b3c0 65 64 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75  ed, as SQLite cu
2b3d0 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20  rrently.** does 
2b3e0 61 6c 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e  all parsing usin
2b3f0 67 20 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54  g UTF-8.  The UT
2b400 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65 73 20  F-16 interfaces 
2b410 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
2b420 61 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  as a convenience
2b430 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e  .  The UTF-16 in
2b440 74 65 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79  terfaces work by
2b450 20 63 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a   converting the.
2b460 2a 2a 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e  ** input text in
2b470 74 6f 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69  to UTF-8, then i
2b480 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72  nvoking the corr
2b490 65 73 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20  esponding UTF-8 
2b4a0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2b4b0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
2b4c0 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
2b4d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b4e0 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
2b4f0 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
2b500 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
2b510 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
2b520 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2b530 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
2b540 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2b550 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
2b560 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
2b570 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
2b580 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
2b590 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
2b5a0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
2b5b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
2b5c0 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
2b5d0 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
2b5e0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
2b5f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
2b600 70 61 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f  pare(), sqlite3_
2b610 70 72 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a  prepare_v2(),.**
2b620 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2b630 70 61 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74  pare_v3().** int
2b640 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
2b650 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
2b660 72 65 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69  repare16(), sqli
2b670 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2b680 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  (),.** and sqlit
2b690 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2b6a0 29 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a  ) use UTF-16..**
2b6b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74  .** ^If the nByt
2b6c0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65  e argument is ne
2b6d0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71  gative, then zSq
2b6e0 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20  l is read up to 
2b6f0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72  the.** first zer
2b700 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49  o terminator. ^I
2b710 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74  f nByte is posit
2b720 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
2b730 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2b740 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
2b750 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74   zSql.  ^If nByt
2b760 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20  e is zero, then 
2b770 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  no prepared.** s
2b780 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65  tatement is gene
2b790 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65  rated..** If the
2b7a0 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68   caller knows th
2b7b0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
2b7c0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
2b7d0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a  rminated, then.*
2b7e0 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  * there is a sma
2b7f0 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ll performance a
2b800 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73  dvantage to pass
2b810 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
2b820 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
2b830 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2b840 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70  bytes in the inp
2b850 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63  ut string <i>inc
2b860 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68  luding</i>.** th
2b870 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72  e nul-terminator
2b880 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
2b890 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
2b8a0 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
2b8b0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
2b8c0 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
2b8d0 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
2b8e0 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
2b8f0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
2b900 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
2b910 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
2b920 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
2b930 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
2b940 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
2b950 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
2b960 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
2b970 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
2b980 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
2b990 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
2b9a0 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
2b9b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2b9c0 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
2b9d0 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
2b9e0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
2b9f0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
2ba00 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
2ba10 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
2ba20 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
2ba30 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
2ba40 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
2ba50 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
2ba60 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
2ba70 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
2ba80 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
2ba90 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
2baa0 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
2bab0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
2bac0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
2bad0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
2bae0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
2baf0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2bb00 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
2bb10 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
2bb20 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
2bb30 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
2bb40 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
2bb50 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2bb60 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
2bb70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
2bb80 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
2bb90 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
2bba0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
2bbb0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
2bbc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2bbd0 76 32 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72  v2(), sqlite3_pr
2bbe0 65 70 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69  epare_v3(), sqli
2bbf0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2bc00 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  (),.** and sqlit
2bc10 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2bc20 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
2bc30 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
2bc40 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
2bc50 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20  s..** The older 
2bc60 69 6e 74 65 72 66 61 63 65 73 20 28 73 71 6c 69  interfaces (sqli
2bc70 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
2bc80 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2bc90 65 31 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65  e16()).** are re
2bca0 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
2bcb0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
2bcc0 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
2bcd0 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
2bce0 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58  ..** ^In the "vX
2bcf0 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
2bd00 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2bd10 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
2bd20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
2bd30 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2bd40 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
2bd50 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
2bd60 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
2bd70 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
2bd80 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
2bd90 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
2bda0 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
2bdb0 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
2bdc0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
2bdd0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
2bde0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
2bdf0 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
2be00 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
2be10 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
2be20 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
2be30 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
2be40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
2be50 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
2be60 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
2be70 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2be80 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
2be90 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
2bea0 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
2beb0 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
2bec0 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
2bed0 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
2bee0 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
2bef0 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
2bf00 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
2bf10 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
2bf20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
2bf30 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
2bf40 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
2bf50 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
2bf60 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
2bf70 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
2bf80 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2bf90 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
2bfa0 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
2bfb0 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
2bfc0 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
2bfd0 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
2bfe0 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
2bff0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
2c000 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
2c010 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
2c020 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
2c030 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2c040 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
2c050 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
2c060 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
2c070 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
2c080 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
2c090 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
2c0a0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
2c0b0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
2c0c0 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
2c0d0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
2c0e0 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
2c0f0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
2c100 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
2c110 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
2c120 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
2c130 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
2c140 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
2c150 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
2c160 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
2c170 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
2c180 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
2c190 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
2c1a0 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
2c1b0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
2c1c0 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
2c1d0 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
2c1e0 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
2c1f0 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
2c200 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
2c210 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
2c220 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
2c230 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
2c240 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
2c250 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
2c260 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
2c270 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
2c280 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
2c290 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
2c2a0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
2c2b0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
2c2c0 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
2c2d0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
2c2e0 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
2c2f0 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
2c300 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
2c310 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
2c320 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
2c330 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
2c340 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
2c350 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
2c360 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
2c370 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
2c380 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
2c390 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e   </ol>.**.** <p>
2c3a0 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  ^sqlite3_prepare
2c3b0 5f 76 33 28 29 20 64 69 66 66 65 72 73 20 66 72  _v3() differs fr
2c3c0 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  om sqlite3_prepa
2c3d0 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20  re_v2() only in 
2c3e0 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78  having.** the ex
2c3f0 74 72 61 20 70 72 65 70 46 6c 61 67 73 20 70 61  tra prepFlags pa
2c400 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 69  rameter, which i
2c410 73 20 61 20 62 69 74 20 61 72 72 61 79 20 63 6f  s a bit array co
2c420 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f  nsisting of zero
2c430 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74   or.** more of t
2c440 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 45 50 41  he [SQLITE_PREPA
2c450 52 45 5f 50 45 52 53 49 53 54 45 4e 54 7c 53 51  RE_PERSISTENT|SQ
2c460 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20  LITE_PREPARE_*] 
2c470 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20  flags.  ^The.** 
2c480 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c490 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77  v2() interface w
2c4a0 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 74 68 65  orks exactly the
2c4b0 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
2c4c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2c4d0 20 77 69 74 68 20 61 20 7a 65 72 6f 20 70 72 65   with a zero pre
2c4e0 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72  pFlags parameter
2c4f0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2c500 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
2c510 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2c520 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2c530 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2c540 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
2c550 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2c560 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
2c570 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2c580 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2c590 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2c5a0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2c5b0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2c5c0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2c5d0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2c5e0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2c5f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
2c600 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2c610 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2c620 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2c630 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2c640 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
2c650 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2c660 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2c670 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2c680 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
2c690 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2c6a0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2c6b0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
2c6c0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2c6d0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2c6e0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2c6f0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2c700 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2c710 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2c720 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2c730 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2c740 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2c750 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2c760 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2c770 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
2c780 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2c790 65 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v3(.  sqlite3 
2c7a0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2c7b0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2c7c0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2c7d0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
2c7e0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2c7f0 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
2c800 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2c810 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2c820 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2c830 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2c840 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69   */.  unsigned i
2c850 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a  nt prepFlags, /*
2c860 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51   Zero or more SQ
2c870 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c  LITE_PREPARE_ fl
2c880 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  ags */.  sqlite3
2c890 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2c8a0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2c8b0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2c8c0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2c8d0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2c8e0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2c8f0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2c900 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2c910 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
2c920 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2c930 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2c940 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2c950 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
2c960 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2c970 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
2c980 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2c990 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2c9a0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2c9b0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2c9c0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2c9d0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2c9e0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2c9f0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2ca00 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2ca10 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2ca20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2ca30 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2ca40 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2ca50 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2ca60 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
2ca70 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2ca80 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2ca90 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2caa0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2cab0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2cac0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2cad0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2cae0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2caf0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2cb00 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2cb10 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2cb20 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2cb30 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2cb40 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2cb50 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2cb60 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2cb70 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2cb80 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2cb90 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2cba0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a  3_prepare16_v3(.
2cbb0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2cbc0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2cbd0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2cbe0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
2cbf0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2cc00 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2cc10 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
2cc20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2cc30 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2cc40 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2cc50 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2cc60 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72   unsigned int pr
2cc70 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f  epFlags, /* Zero
2cc80 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f   or more SQLITE_
2cc90 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a  PREPARE_ flags *
2cca0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2ccb0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2ccc0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2ccd0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2cce0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2ccf0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2cd00 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2cd10 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2cd20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2cd30 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
2cd40 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d  atement SQL.** M
2cd50 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2cd60 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2cd70 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e  qlite3_sql(P) in
2cd80 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2cd90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63  a pointer to a c
2cda0 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38  opy of the UTF-8
2cdb0 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
2cdc0 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65  d to create [pre
2cdd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cde0 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63   P if P was.** c
2cdf0 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74  reated by [sqlit
2ce00 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2ce10 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
2ce20 72 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v3()],.** [sq
2ce30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2ce40 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  v2()], or [sqlit
2ce50 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
2ce60 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
2ce70 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2ce80 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2ce90 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2cea0 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74  to a UTF-8.** st
2ceb0 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
2cec0 74 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20  the SQL text of 
2ced0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cee0 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f  nt P with.** [bo
2cef0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20  und parameters] 
2cf00 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  expanded..**.** 
2cf10 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
2cf20 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  f a prepared sta
2cf30 74 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65  tement is create
2cf40 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a  d using the SQL.
2cf50 2a 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20  ** text "SELECT 
2cf60 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69  $abc,:xyz" and i
2cf70 66 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63  f parameter $abc
2cf80 20 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74   is bound to int
2cf90 65 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64  eger 2345.** and
2cfa0 20 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20   parameter :xyz 
2cfb0 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e  is unbound, then
2cfc0 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77   sqlite3_sql() w
2cfd0 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68  ill return.** th
2cfe0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e  e original strin
2cff0 67 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c  g, "SELECT $abc,
2d000 3a 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65  :xyz" but sqlite
2d010 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2d020 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
2d030 22 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c  "SELECT 2345,NUL
2d040 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  L".)^.**.** ^The
2d050 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2d060 64 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63  d_sql() interfac
2d070 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69  e returns NULL i
2d080 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d  f insufficient m
2d090 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69  emory.** is avai
2d0a0 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68  lable to hold th
2d0b0 65 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20  e result, or if 
2d0c0 74 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64  the result would
2d0d0 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74   exceed the.** t
2d0e0 68 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e  he maximum strin
2d0f0 67 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69  g length determi
2d100 6e 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49  ned by the [SQLI
2d110 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2d120 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
2d130 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
2d140 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  LIMIT] compile-t
2d150 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74  ime option limit
2d160 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  s the size of.**
2d170 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72   bound parameter
2d180 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54   expansions.  ^T
2d190 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
2d1a0 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74  TRACE] compile-t
2d1b0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61  ime.** option ca
2d1c0 75 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70  uses sqlite3_exp
2d1d0 61 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61  anded_sql() to a
2d1e0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c  lways return NUL
2d1f0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74  L..**.** ^The st
2d200 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79  ring returned by
2d210 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20   sqlite3_sql(P) 
2d220 69 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51  is managed by SQ
2d230 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61  Lite and is.** a
2d240 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2d250 65 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70  ed when the prep
2d260 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2d270 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20  s finalized..** 
2d280 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75  ^The string retu
2d290 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2d2a0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c  expanded_sql(P),
2d2b0 20 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61   on the other ha
2d2c0 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e  nd,.** is obtain
2d2d0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2d2e0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d  _malloc()] and m
2d2f0 75 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74  ust be free by t
2d300 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
2d310 2a 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20  * by passing it 
2d320 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
2d330 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
2d340 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
2d350 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2d360 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  tmt);.char *sqli
2d370 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2d380 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2d390 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2d3a0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
2d3b0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
2d3c0 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68 65  ement Writes The
2d3d0 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54   Database.** MET
2d3e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2d3f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2d400 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2d410 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
2d420 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
2d430 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
2d440 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
2d450 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d460 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
2d470 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
2d480 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
2d490 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
2d4a0 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
2d4b0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
2d4c0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2d4d0 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
2d4e0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
2d4f0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
2d500 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
2d510 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
2d520 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
2d530 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
2d540 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
2d550 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
2d560 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
2d570 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
2d580 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
2d590 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
2d5a0 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
2d5b0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
2d5c0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
2d5d0 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
2d5e0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
2d5f0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
2d600 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
2d610 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
2d620 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
2d630 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
2d640 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
2d650 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2d660 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2d670 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2d680 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
2d690 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
2d6a0 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
2d6b0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
2d6c0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
2d6d0 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
2d6e0 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
2d6f0 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
2d700 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
2d710 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
2d720 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
2d730 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
2d740 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2d750 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
2d760 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
2d770 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
2d780 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
2d790 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
2d7a0 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
2d7b0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
2d7c0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
2d7d0 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
2d7e0 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
2d7f0 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
2d800 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
2d810 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
2d820 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
2d830 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
2d840 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2d850 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
2d860 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
2d870 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
2d880 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
2d890 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
2d8a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d8b0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
2d8c0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
2d8d0 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
2d8e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2d8f0 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20  les on disk..** 
2d900 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2d910 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74  t_readonly() int
2d920 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2d930 72 75 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20  rue for [BEGIN] 
2d940 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d  since.** [BEGIN]
2d950 20 6d 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74   merely sets int
2d960 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74  ernal flags, but
2d970 20 74 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49   the [BEGIN|BEGI
2d980 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64  N IMMEDIATE] and
2d990 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e  .** [BEGIN|BEGIN
2d9a0 20 45 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d   EXCLUSIVE] comm
2d9b0 61 6e 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68  ands do touch th
2d9c0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 73  e database and s
2d9d0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  o.** sqlite3_stm
2d9e0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74  t_readonly() ret
2d9f0 75 72 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74  urns false for t
2da00 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a  hose commands..*
2da10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
2da20 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
2da30 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2da40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2da50 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2da60 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2da70 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
2da80 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
2da90 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2daa0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2dab0 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
2dac0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2dad0 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2dae0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2daf0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
2db00 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
2db10 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
2db20 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2db30 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
2db40 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f  s neither run to
2db50 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74   completion (ret
2db60 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2db70 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c  _DONE] from [sql
2db80 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e  ite3_step(S)]) n
2db90 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74  or.** been reset
2dba0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2dbb0 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65  reset(S)].  ^The
2dbc0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2dbd0 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61  sy(S).** interfa
2dbe0 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  ce returns false
2dbf0 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20   if S is a NULL 
2dc00 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69  pointer.  If S i
2dc10 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c  s not a .** NULL
2dc20 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20   pointer and is 
2dc30 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  not a pointer to
2dc40 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72   a valid [prepar
2dc50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2dc60 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68   object, then th
2dc70 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2dc80 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2dc90 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
2dca0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2dcb0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2dcc0 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f  ed in combinatio
2dcd0 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
2dce0 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f  stmt()].** to lo
2dcf0 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65  cate all prepare
2dd00 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
2dd10 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64  ociated with a d
2dd20 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e  atabase .** conn
2dd30 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20  ection that are 
2dd40 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67  in need of being
2dd50 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61   reset.  This ca
2dd60 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f  n be used,.** fo
2dd70 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69  r example, in di
2dd80 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65  agnostic routine
2dd90 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20  s to search for 
2dda0 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61  prepared .** sta
2ddb0 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  tements that are
2ddc0 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73   holding a trans
2ddd0 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a  action open..*/.
2dde0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
2ddf0 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74  _busy(sqlite3_st
2de00 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2de10 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
2de20 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
2de30 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
2de40 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
2de50 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
2de60 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2de70 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
2de80 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
2de90 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2dea0 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
2deb0 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
2dec0 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
2ded0 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
2dee0 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
2def0 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
2df00 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
2df10 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
2df20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
2df30 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2df40 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
2df50 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
2df60 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2df70 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
2df80 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
2df90 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
2dfa0 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
2dfb0 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
2dfc0 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
2dfd0 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
2dfe0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2dff0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2e000 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
2e010 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
2e020 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
2e030 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
2e040 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2e050 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2e060 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
2e070 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
2e080 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
2e090 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
2e0a0 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
2e0b0 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
2e0c0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2e0d0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65  ite3_value.  The
2e0e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2e0f0 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66  ue_dup()] interf
2e100 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2e110 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e  to construct a n
2e120 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64  ew .** protected
2e130 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66   sqlite3_value f
2e140 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  rom an unprotect
2e150 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e160 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
2e170 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
2e180 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
2e190 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
2e1a0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
2e1b0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
2e1c0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
2e1d0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
2e1e0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2e1f0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
2e200 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
2e210 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
2e220 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2e230 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
2e240 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
2e250 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
2e260 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
2e270 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
2e280 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
2e290 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
2e2a0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
2e2b0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
2e2c0 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
2e2d0 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
2e2e0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
2e2f0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
2e300 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
2e310 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2e320 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
2e330 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
2e340 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
2e350 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2e360 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2e370 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2e380 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
2e390 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
2e3a0 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
2e3b0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
2e3c0 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
2e3d0 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
2e3e0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
2e3f0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
2e400 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
2e410 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2e420 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2e430 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2e440 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e450 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
2e460 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
2e470 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
2e480 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2e490 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
2e4a0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
2e4b0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
2e4c0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
2e4d0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
2e4e0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2e4f0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
2e500 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
2e510 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2e520 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2e530 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2e540 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2e550 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
2e560 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2e570 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e580 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2e590 64 20 61 73 20 61 72 67 75 6d 65 6e 74 73 0a 2a  d as arguments.*
2e5a0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  * to [sqlite3_re
2e5b0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c 20 5b  sult_value()], [
2e5c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2e5d0 75 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  ue()], and.** [s
2e5e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
2e5f0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
2e600 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
2e610 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
2e620 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
2e630 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
2e640 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
2e650 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2e660 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
2e670 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2e680 65 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33  e3_value sqlite3
2e690 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
2e6a0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
2e6b0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
2e6c0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
2e6d0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
2e6e0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
2e6f0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
2e700 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
2e710 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2e720 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
2e730 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
2e740 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
2e750 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
2e760 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
2e770 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e780 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2e790 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
2e7a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2e7b0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2e7c0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
2e7d0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
2e7e0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
2e7f0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2e800 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
2e810 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
2e820 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
2e830 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2e840 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
2e850 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
2e860 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2e870 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
2e880 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2e890 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
2e8a0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2e8b0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
2e8c0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2e8d0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
2e8e0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
2e8f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
2e900 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
2e910 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2e920 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
2e930 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
2e940 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2e950 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
2e960 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
2e970 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
2e980 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
2e990 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
2e9a0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45  r binding}.** ME
2e9b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2e9c0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  mt.**.** ^(In th
2e9d0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2e9e0 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
2e9f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ea00 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
2ea10 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
2ea20 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
2ea30 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
2ea40 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
2ea50 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
2ea60 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
2ea70 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2ea80 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
2ea90 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
2eaa0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
2eab0 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
2eac0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2ead0 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
2eae0 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
2eaf0 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
2eb00 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
2eb10 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
2eb20 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
2eb30 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
2eb40 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
2eb50 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
2eb60 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
2eb70 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
2eb80 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
2eb90 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
2eba0 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
2ebb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2ebc0 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
2ebd0 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
2ebe0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2ebf0 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
2ec00 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2ec10 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
2ec20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2ec30 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
2ec40 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2ec50 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
2ec60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2ec70 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
2ec80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2ec90 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2eca0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2ecb0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
2ecc0 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
2ecd0 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
2ece0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2ecf0 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
2ed00 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
2ed10 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
2ed20 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
2ed30 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
2ed40 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
2ed50 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
2ed60 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
2ed70 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
2ed80 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
2ed90 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
2eda0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
2edb0 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
2edc0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
2edd0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ede0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
2edf0 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
2ee00 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
2ee10 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
2ee20 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
2ee30 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
2ee40 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
2ee50 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
2ee60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
2ee70 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
2ee80 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
2ee90 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2eea0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
2eeb0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
2eec0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2eed0 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
2eee0 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
2eef0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
2ef00 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2ef10 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2ef20 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2ef30 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2ef40 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  6().** or sqlite
2ef50 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2ef60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2ef70 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2ef80 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
2ef90 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20  ignored and the 
2efa0 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68  end result is th
2efb0 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65  e same as sqlite
2efc0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a  3_bind_null()..*
2efd0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
2efe0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
2eff0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
2f000 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
2f010 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2f020 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2f030 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
2f040 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
2f050 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2f060 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
2f070 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
2f080 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
2f090 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2f0a0 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
2f0b0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2f0c0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2f0d0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2f0e0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2f0f0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2f100 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  hen the length o
2f110 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
2f120 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2f130 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
2f140 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2f150 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68  inator..** If th
2f160 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2f170 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2f180 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67  nd_blob() is neg
2f190 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74  ative, then.** t
2f1a0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2f1b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2f1c0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
2f1d0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2f1e0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
2f1f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2f200 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2f210 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f  _bind_text16() o
2f220 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2f230 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20  ext64() then.** 
2f240 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
2f250 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
2f260 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
2f270 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
2f280 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
2f290 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
2f2a0 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
2f2b0 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
2f2c0 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
2f2d0 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
2f2e0 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
2f2f0 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
2f300 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
2f310 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
2f320 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
2f330 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
2f340 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
2f350 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
2f360 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
2f370 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
2f380 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
2f390 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
2f3a0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2f3b0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2f3c0 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e  t to the BLOB an
2f3d0 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67  d string binding
2f3e0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2f3f0 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
2f400 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
2f410 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
2f420 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
2f430 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
2f440 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
2f450 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2f460 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
2f470 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2f480 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
2f490 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69  f the call to bi
2f4a0 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a  nd API fails..**
2f4b0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2f4c0 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
2f4d0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
2f4e0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
2f4f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
2f500 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
2f510 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2f520 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
2f530 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
2f540 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2f550 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
2f560 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2f570 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
2f580 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
2f590 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
2f5a0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
2f5b0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2f5c0 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
2f5d0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
2f5e0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
2f5f0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
2f600 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
2f610 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  The sixth argume
2f620 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2f630 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74  nd_text64() must
2f640 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53   be one of.** [S
2f650 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
2f660 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51  LITE_UTF16], [SQ
2f670 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
2f680 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
2f690 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79  E].** to specify
2f6a0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
2f6b0 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65   the text in the
2f6c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2f6d0 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78  .  If.** the six
2f6e0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2f6f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2f700 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  64() is not one 
2f710 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65  of the.** allowe
2f720 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61  d values shown a
2f730 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20  bove, or if the 
2f740 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73  text encoding is
2f750 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72   different.** fr
2f760 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  om the encoding 
2f770 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2f780 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
2f790 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2f7a0 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
2f7b0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2f7c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2f7d0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
2f7e0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
2f7f0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
2f800 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
2f810 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
2f820 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
2f830 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
2f840 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
2f850 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
2f860 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
2f870 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
2f880 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
2f890 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
2f8a0 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
2f8b0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
2f8c0 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
2f8d0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
2f8e0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
2f8f0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
2f900 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
2f910 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
2f920 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
2f930 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
2f940 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
2f950 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
2f960 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54  h BLOB..**.** ^T
2f970 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2f980 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c 54 2c  pointer(S,I,P,T,
2f990 44 29 20 72 6f 75 74 69 6e 65 20 63 61 75 73 65  D) routine cause
2f9a0 73 20 74 68 65 20 49 2d 74 68 20 70 61 72 61 6d  s the I-th param
2f9b0 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 65 70  eter in.** [prep
2f9c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f9d0 53 20 74 6f 20 68 61 76 65 20 61 6e 20 53 51 4c  S to have an SQL
2f9e0 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c 2c 20   value of NULL, 
2f9f0 62 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 0a 2a  but to also be.*
2fa00 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
2fa10 68 20 74 68 65 20 70 6f 69 6e 74 65 72 20 50 20  h the pointer P 
2fa20 6f 66 20 74 79 70 65 20 54 2e 20 20 5e 44 20 69  of type T.  ^D i
2fa30 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
2fa40 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 61 20  pointer or.** a 
2fa50 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65 73  pointer to a des
2fa60 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
2fa70 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 65 20   for P. ^SQLite 
2fa80 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 0a  will invoke the.
2fa90 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 44 20  ** destructor D 
2faa0 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 61 72  with a single ar
2fab0 67 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 65 6e  gument of P when
2fac0 20 69 74 20 69 73 20 66 69 6e 69 73 68 65 64 20   it is finished 
2fad0 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 68 65  using.** P.  The
2fae0 20 54 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f   T parameter sho
2faf0 75 6c 64 20 62 65 20 61 20 73 74 61 74 69 63 20  uld be a static 
2fb00 73 74 72 69 6e 67 2c 20 70 72 65 66 65 72 61 62  string, preferab
2fb10 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a 20 6c  ly a string.** l
2fb20 69 74 65 72 61 6c 2e 20 54 68 65 20 73 71 6c 69  iteral. The sqli
2fb30 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72  te3_bind_pointer
2fb40 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  () routine is pa
2fb50 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 70 6f  rt of the.** [po
2fb60 69 6e 74 65 72 20 70 61 73 73 69 6e 67 20 69 6e  inter passing in
2fb70 74 65 72 66 61 63 65 5d 20 61 64 64 65 64 20 66  terface] added f
2fb80 6f 72 20 53 51 4c 69 74 65 20 33 2e 32 30 2e 30  or SQLite 3.20.0
2fb90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
2fba0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
2fbb0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2fbc0 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
2fbd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2fbe0 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
2fbf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fc00 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
2fc10 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
2fc20 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
2fc30 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
2fc40 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
2fc50 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
2fc60 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2fc70 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
2fc80 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
2fc90 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2fca0 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
2fcb0 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
2fcc0 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
2fcd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fce0 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
2fcf0 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
2fd00 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
2fd10 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2fd20 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
2fd30 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
2fd40 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
2fd50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
2fd60 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
2fd70 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
2fd80 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
2fd90 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
2fda0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2fdb0 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
2fdc0 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2fdd0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
2fde0 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
2fdf0 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
2fe00 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
2fe10 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47   ^[SQLITE_TOOBIG
2fe20 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2fe30 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20  ned if the size 
2fe40 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  of a string or B
2fe50 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c  LOB.** exceeds l
2fe60 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79  imits imposed by
2fe70 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
2fe80 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  ([SQLITE_LIMIT_L
2fe90 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53  ENGTH]) or.** [S
2fea0 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48  QLITE_MAX_LENGTH
2feb0 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  ]..** ^[SQLITE_R
2fec0 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
2fed0 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
2fee0 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
2fef0 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
2ff00 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
2ff10 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
2ff20 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
2ff30 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2ff40 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2ff50 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
2ff60 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2ff70 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2ff80 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2ff90 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2ffa0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
2ffb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ffc0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2ffd0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2ffe0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
2fff0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
30000 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
30010 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
30020 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
30030 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
30040 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
30050 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
30060 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
30070 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
30080 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
30090 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
300a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
300b0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
300c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
300d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
300e0 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
300f0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
30100 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
30110 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
30120 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
30130 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
30140 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
30150 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63  ite3_stmt*,int,c
30160 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76  onst char*,int,v
30170 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
30180 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
30190 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
301a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
301b0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
301c0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
301d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
301e0 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73  text64(sqlite3_s
301f0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
30200 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
30210 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
30220 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30230 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
30240 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
30250 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71  ncoding);.int sq
30260 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
30270 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30280 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
30290 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
302a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69  sqlite3_bind_poi
302b0 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d  nter(sqlite3_stm
302c0 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20  t*, int, void*, 
302d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 76 6f 69 64  const char*,void
302e0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
302f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
30300 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
30310 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
30320 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
30330 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73  ind_zeroblob64(s
30340 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30350 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  t, sqlite3_uint6
30360 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
30370 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
30380 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
30390 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
303a0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  _stmt.**.** ^Thi
303b0 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
303c0 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
303d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
303e0 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
303f0 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
30400 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
30410 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
30420 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
30430 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
30440 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
30450 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
30460 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
30470 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
30480 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
30490 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
304a0 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
304b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
304c0 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
304d0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
304e0 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
304f0 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
30500 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
30510 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
30520 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
30530 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
30540 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
30550 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
30560 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
30570 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
30580 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
30590 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
305a0 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
305b0 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
305c0 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
305d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
305e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
305f0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
30600 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
30610 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
30620 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
30630 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30640 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
30650 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
30660 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
30670 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
30680 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30690 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
306a0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st Parameter.** 
306b0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
306c0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
306d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
306e0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
306f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30700 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
30710 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
30720 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
30730 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
30740 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
30750 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
30760 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
30770 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
30780 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
30790 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
307a0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
307b0 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
307c0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
307d0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
307e0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
307f0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
30800 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
30810 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
30820 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
30830 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
30840 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
30850 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
30860 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
30870 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
30880 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
30890 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
308a0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
308b0 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
308c0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
308d0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
308e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
308f0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
30900 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
30910 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
30920 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
30930 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
30940 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
30950 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
30960 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
30970 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
30980 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
30990 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
309a0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
309b0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
309c0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
309d0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
309e0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
309f0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a  _prepare16()],.*
30a00 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
30a10 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b  re16_v2()], or [
30a20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
30a30 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v3()]..**.** S
30a40 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
30a50 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
30a60 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
30a70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
30a80 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
30a90 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
30aa0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30ab0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
30ac0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
30ad0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30ae0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
30af0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
30b00 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
30b10 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
30b20 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
30b30 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  me.** METHOD: sq
30b40 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
30b50 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
30b60 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
30b70 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
30b80 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
30b90 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
30ba0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
30bb0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
30bc0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
30bd0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
30be0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
30bf0 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
30c00 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
30c10 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
30c20 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
30c30 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
30c40 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
30c50 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
30c60 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
30c70 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
30c80 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
30c90 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
30ca0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
30cb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
30cc0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
30cd0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
30ce0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
30cf0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
30d00 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
30d10 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
30d20 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30d30 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
30d40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
30d50 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
30d60 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
30d70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30d80 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
30d90 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
30da0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
30db0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
30dc0 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
30dd0 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
30de0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
30df0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30e00 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
30e10 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
30e20 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
30e30 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
30e40 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
30e50 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
30e60 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
30e70 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
30e80 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
30e90 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
30ea0 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
30eb0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
30ec0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
30ed0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
30ee0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
30ef0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
30f00 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
30f10 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
30f20 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
30f30 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30f40 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
30f50 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
30f60 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
30f70 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
30f80 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
30f90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
30fa0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
30fb0 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20  returns 0, that 
30fc0 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70  means the .** [p
30fd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30fe0 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61  t] returns no da
30ff0 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
31000 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
31010 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20   ^However, just 
31020 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f 75  because this rou
31030 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
31040 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64  ositive number d
31050 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20  oes not.** mean 
31060 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  that one or more
31070 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69   rows of data wi
31080 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ll be returned. 
31090 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74 65   ^A SELECT state
310a0 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77  ment.** will alw
310b0 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69 74  ays have a posit
310c0 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ive sqlite3_colu
310d0 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64  mn_count() but d
310e0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a  epending on the.
310f0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
31100 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
31110 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e  the table conten
31120 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74 75  t, it might retu
31130 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a  rn no rows..**.*
31140 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
31150 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
31160 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
31170 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
31180 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
31190 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
311a0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
311b0 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
311c0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
311d0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
311e0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
311f0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
31200 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
31210 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
31220 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
31230 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
31240 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
31250 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
31260 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
31270 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
31280 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
31290 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
312a0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
312b0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
312c0 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
312d0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
312e0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
312f0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
31300 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
31310 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
31320 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31330 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
31340 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
31350 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
31360 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
31370 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
31380 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
31390 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
313a0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
313b0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
313c0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
313d0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
313e0 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
313f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31400 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
31410 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
31420 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
31430 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
31440 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
31450 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
31460 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
31470 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
31480 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
31490 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
314a0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
314b0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
314c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
314d0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
314e0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
314f0 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
31500 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
31510 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
31520 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
31530 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
31540 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
31550 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
31560 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
31570 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
31580 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
31590 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
315a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
315b0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
315c0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
315d0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
315e0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
315f0 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
31600 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
31610 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
31620 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
31630 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
31640 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
31650 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
31660 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
31670 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
31680 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
31690 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
316a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
316b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
316c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
316d0 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
316e0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
316f0 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
31700 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
31710 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31720 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
31730 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
31740 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31750 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31760 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
31770 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20  provide a means 
31780 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  to determine the
31790 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
317a0 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63  , and.** table c
317b0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68  olumn that is th
317c0 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61  e origin of a pa
317d0 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20  rticular result 
317e0 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45  column in.** [SE
317f0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
31800 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
31810 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
31820 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
31830 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
31840 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
31850 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
31860 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
31870 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
31880 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
31890 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
318a0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
318b0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
318c0 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
318d0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
318e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
318f0 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
31900 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
31910 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
31920 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
31930 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
31940 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
31950 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
31960 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
31970 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
31980 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
31990 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
319a0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
319b0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
319c0 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
319d0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
319e0 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
319f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
31a00 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
31a10 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
31a20 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
31a30 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
31a40 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
31a50 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
31a60 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
31a70 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
31a80 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
31a90 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
31aa0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65  rgument to these
31ab0 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61   interfaces is a
31ac0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31ad0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65  ment]..** ^These
31ae0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
31af0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
31b00 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75  out the Nth resu
31b10 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  lt column return
31b20 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61  ed by.** the sta
31b30 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20  tement, where N 
31b40 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  is the second fu
31b50 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
31b60 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f  .** ^The left-mo
31b70 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c  st column is col
31b80 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20  umn 0 for these 
31b90 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
31ba0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
31bb0 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  mn returned by t
31bc0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
31bd0 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  an expression or
31be0 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64  .** subquery and
31bf0 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e   is not a column
31c00 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c   value, then all
31c10 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
31c20 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55  ons return.** NU
31c30 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  LL.  ^These rout
31c40 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72  ine might also r
31c50 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20  eturn NULL if a 
31c60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
31c70 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72  n error.** occur
31c80 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20  s.  ^Otherwise, 
31c90 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20  they return the 
31ca0 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61  name of the atta
31cb0 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74  ched database, t
31cc0 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75  able,.** or colu
31cd0 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65  mn that query re
31ce0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20  sult column was 
31cf0 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a  extracted from..
31d00 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61  **.** ^As with a
31d10 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ll other SQLite 
31d20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73  APIs, those whos
31d30 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68  e names end with
31d40 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
31d50 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
31d60 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f  trings and the o
31d70 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72  ther functions r
31d80 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a  eturn UTF-8..**.
31d90 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61  ** ^These APIs a
31da0 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  re only availabl
31db0 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79  e if the library
31dc0 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
31dd0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
31de0 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f  E_ENABLE_COLUMN_
31df0 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70  METADATA] C-prep
31e00 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e  rocessor symbol.
31e10 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
31e20 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
31e30 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  ll one or more o
31e40 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
31e50 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d   against the sam
31e60 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  e.** prepared st
31e70 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75  atement and colu
31e80 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  mn at the same t
31e90 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
31ea0 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65  ults are.** unde
31eb0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  fined..**.** If 
31ec0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
31ed0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
31ee0 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  more.** [sqlite3
31ef0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
31f00 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d  _name | column m
31f10 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63  etadata interfac
31f20 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  es].** for the s
31f30 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
31f40 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73  atement] and res
31f50 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74  ult column.** at
31f60 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
31f70 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
31f80 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
31f90 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
31fa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
31fb0 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74  abase_name(sqlit
31fc0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
31fd0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31fe0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
31ff0 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
32000 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
32010 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
32020 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
32030 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
32040 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
32050 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
32060 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28  mn_table_name16(
32070 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
32080 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
32090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
320a0 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
320b0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
320c0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
320d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
320e0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
320f0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
32100 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
32110 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
32120 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
32130 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
32140 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
32150 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
32160 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
32170 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
32180 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
32190 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
321a0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
321b0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
321c0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
321d0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
321e0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
321f0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
32200 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
32210 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
32220 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
32230 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
32240 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
32250 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
32260 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
32270 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
32280 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
32290 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
322a0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
322b0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
322c0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
322d0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
322e0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
322f0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
32300 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
32310 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
32320 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
32330 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
32340 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
32350 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
32360 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
32370 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
32380 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
32390 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
323a0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
323b0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
323c0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
323d0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
323e0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
323f0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
32400 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
32410 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
32420 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
32430 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
32440 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
32450 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
32460 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
32470 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
32480 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
32490 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
324a0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
324b0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
324c0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
324d0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
324e0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
324f0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
32500 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
32510 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
32520 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
32530 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
32540 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
32550 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
32560 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
32570 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
32580 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
32590 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
325a0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
325b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
325c0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
325d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
325e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
325f0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
32600 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
32610 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
32620 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
32630 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
32640 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
32650 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41  te3_stmt.**.** A
32660 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
32670 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
32680 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
32690 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b 73  ing any of.** [s
326a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
326b0 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  2()], [sqlite3_p
326c0 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73  repare_v3()], [s
326d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
326e0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  _v2()],.** or [s
326f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32700 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v3()] or one of
32710 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
32720 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
32730 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
32740 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32750 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
32760 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
32770 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
32780 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
32790 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
327a0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
327b0 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
327c0 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
327d0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
327e0 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
327f0 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
32800 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
32810 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
32820 20 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74 65   newer "vX" inte
32830 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  rfaces.** [sqlit
32840 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
32850 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
32860 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
32870 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
32880 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
32890 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
328a0 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
328b0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
328c0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
328d0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
328e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
328f0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
32900 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e 74  .** new "vX" int
32910 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
32920 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
32930 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
32940 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
32950 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
32960 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
32970 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
32980 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
32990 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
329a0 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
329b0 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
329c0 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
329d0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
329e0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
329f0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
32a00 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
32a10 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
32a20 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
32a30 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
32a40 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
32a50 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
32a60 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
32a70 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
32a80 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
32a90 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
32aa0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
32ab0 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
32ac0 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
32ad0 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
32ae0 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
32af0 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
32b00 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
32b10 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
32b20 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
32b30 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
32b40 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
32b50 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
32b60 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
32b70 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
32b80 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
32b90 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
32ba0 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63  hin an.** explic
32bb0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  it transaction t
32bc0 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72  hen you should r
32bd0 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ollback the tran
32be0 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a  saction before.*
32bf0 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a  * continuing..**
32c00 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e  .** ^[SQLITE_DON
32c10 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
32c20 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20  e statement has 
32c30 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
32c40 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c  ng.** successful
32c50 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ly.  sqlite3_ste
32c60 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
32c70 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
32c80 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a  n this virtual.*
32c90 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75  * machine withou
32ca0 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20  t first calling 
32cb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32cc0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76  ] to reset the v
32cd0 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e  irtual.** machin
32ce0 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  e back to its in
32cf0 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a  itial state..**.
32d00 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73  ** ^If the SQL s
32d10 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
32d20 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
32d30 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
32d40 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
32d50 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
32d60 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
32d70 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
32d80 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
32d90 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
32da0 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
32db0 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
32dc0 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
32dd0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
32de0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
32df0 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
32e00 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
32e10 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
32e20 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ata..**.** ^[SQL
32e30 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73  ITE_ERROR] means
32e40 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65   that a run-time
32e50 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20   error (such as 
32e60 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20  a constraint.** 
32e70 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f  violation) has o
32e80 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65  ccurred.  sqlite
32e90 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
32ea0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
32eb0 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d  ain on.** the VM
32ec0 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69  . More informati
32ed0 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20  on may be found 
32ee0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
32ef0 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
32f00 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61  * ^With the lega
32f10 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20  cy interface, a 
32f20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
32f30 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78  ror code (for ex
32f40 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ample,.** [SQLIT
32f50 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53  E_INTERRUPT], [S
32f60 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b  QLITE_SCHEMA], [
32f70 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c  SQLITE_CORRUPT],
32f80 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a   and so forth).*
32f90 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  * can be obtaine
32fa0 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
32fb0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
32fc0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
32fd0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
32fe0 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
32ff0 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d  erface,.** the m
33000 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
33010 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72  or code is retur
33020 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20  ned directly by 
33030 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a  sqlite3_step()..
33040 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49  **.** [SQLITE_MI
33050 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  SUSE] means that
33060 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e   the this routin
33070 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61  e was called ina
33080 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a  ppropriately..**
33090 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20   Perhaps it was 
330a0 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65  called on a [pre
330b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
330c0 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72   that has.** alr
330d0 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74  eady been [sqlit
330e0 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69  e3_finalize | fi
330f0 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f  nalized] or on o
33100 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70  ne that had.** p
33110 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
33120 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ed [SQLITE_ERROR
33130 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
33140 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64  E].  Or it could
33150 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20  .** be the case 
33160 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61  that the same da
33170 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
33180 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  n is being used 
33190 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72  by two or.** mor
331a0 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  e threads at the
331b0 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20   same moment in 
331c0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  time..**.** For 
331d0 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  all versions of 
331e0 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64  SQLite up to and
331f0 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32   including 3.6.2
33200 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a  3.1, a call to.*
33210 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
33220 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64  ()] was required
33230 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73   after sqlite3_s
33240 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61  tep() returned a
33250 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  nything.** other
33260 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
33270 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75  W] before any su
33280 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
33290 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ion of.** sqlite
332a0 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75  3_step().  Failu
332b0 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  re to reset the 
332c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
332d0 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  nt using .** [sq
332e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
332f0 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61  ould result in a
33300 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
33310 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a  ] return from.**
33320 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
33330 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72    But after [ver
33340 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28  sion 3.6.23.1] (
33350 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31  [dateof:3.6.23.1
33360 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ],.** sqlite3_st
33370 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61  ep() began.** ca
33380 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
33390 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69  eset()] automati
333a0 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69  cally in this ci
333b0 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65  rcumstance rathe
333c0 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e  r.** than return
333d0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  ing [SQLITE_MISU
333e0 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f  SE].  This is no
333f0 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63  t considered a c
33400 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20  ompatibility.** 
33410 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e  break because an
33420 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  y application th
33430 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73  at ever receives
33440 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   an SQLITE_MISUS
33450 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72  E error.** is br
33460 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69  oken by definiti
33470 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  on.  The [SQLITE
33480 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d  _OMIT_AUTORESET]
33490 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
334a0 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75  tion.** can be u
334b0 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74  sed to restore t
334c0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
334d0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f  or..**.** <b>Goo
334e0 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65  fy Interface Ale
334f0 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c  rt:</b> In the l
33500 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
33510 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
33520 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79  p().** API alway
33530 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65  s returns a gene
33540 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20  ric error code, 
33550 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
33560 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a  following any.**
33570 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61   error other tha
33580 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
33590 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  and [SQLITE_MISU
335a0 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63  SE].  You must c
335b0 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
335c0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
335d0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
335e0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
335f0 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  d one of the.** 
33600 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
33610 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74  codes] that bett
33620 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65  er describes the
33630 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64   error..** We ad
33640 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73  mit that this is
33650 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e   a goofy design.
33660 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61    The problem ha
33670 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20  s been fixed.** 
33680 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  with the "v2" in
33690 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75  terface.  If you
336a0 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20   prepare all of 
336b0 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65  your SQL stateme
336c0 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  nts.** using [sq
336d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
336e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
336f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a 2a  prepare_v2()].**
33700 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
33710 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
33720 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33730 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61 64  16_v3()] instead
33740 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
33750 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
33760 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
33770 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
33780 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
33790 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
337a0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
337b0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
337c0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
337d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
337e0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
337f0 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 20  "vX" interfaces 
33800 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
33810 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
33820 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
33830 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
33840 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
33850 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
33860 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt set.** METHOD
33870 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
33880 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33890 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
338a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
338b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
338c0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
338d0 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
338e0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
338f0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
33900 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
33910 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
33920 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
33930 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
33940 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
33950 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
33960 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
33970 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
33980 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
33990 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
339a0 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
339b0 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
339c0 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
339d0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
339e0 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
339f0 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
33a00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
33a10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33a20 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
33a30 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
33a40 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
33a50 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
33a60 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
33a70 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
33a80 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
33a90 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
33aa0 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
33ab0 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
33ac0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
33ad0 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
33ae0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
33af0 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
33b00 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
33b10 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
33b20 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
33b30 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
33b40 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
33b50 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
33b60 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
33b70 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
33b80 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
33b90 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
33ba0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
33bb0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
33bc0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33bd0 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
33be0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
33bf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33c00 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
33c10 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
33c20 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
33c30 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
33c40 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
33c50 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
33c60 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
33c70 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
33c80 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
33c90 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
33ca0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
33cb0 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
33cc0 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
33cd0 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
33ce0 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
33cf0 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
33d00 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
33d10 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
33d20 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
33d30 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
33d40 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
33d50 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
33d60 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
33d70 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
33d80 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
33d90 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
33da0 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
33db0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
33dc0 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
33dd0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
33de0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
33df0 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
33e00 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
33e10 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
33e20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
33e30 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
33e40 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
33e50 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
33e60 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
33e70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33e80 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
33e90 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
33ea0 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
33eb0 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
33ec0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
33ed0 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
33ee0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
33ef0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
33f00 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
33f10 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
33f20 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
33f30 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
33f40 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
33f50 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
33f60 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79  **.** <b>Summary
33f70 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  :</b>.** <blockq
33f80 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64  uote><table bord
33f90 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67  er=0 cellpadding
33fa0 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30  =0 cellspacing=0
33fb0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  >.** <tr><td><b>
33fc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33fd0 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  lob</b><td>&rarr
33fe0 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74  ;<td>BLOB result
33ff0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34000 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
34010 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  uble</b><td>&rar
34020 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75 6c  r;<td>REAL resul
34030 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
34040 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
34050 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  nt</b><td>&rarr;
34060 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45 47  <td>32-bit INTEG
34070 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  ER result.** <tr
34080 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
34090 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e  column_int64</b>
340a0 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34  <td>&rarr;<td>64
340b0 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73  -bit INTEGER res
340c0 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
340d0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
340e0 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61  _text</b><td>&ra
340f0 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45 58  rr;<td>UTF-8 TEX
34100 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  T result.** <tr>
34110 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
34120 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e  olumn_text16</b>
34130 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54  <td>&rarr;<td>UT
34140 46 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c 74  F-16 TEXT result
34150 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
34170 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  lue</b><td>&rarr
34180 3b 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74 20  ;<td>The result 
34190 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74  as an .** [sqlit
341a0 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65  e3_value|unprote
341b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
341c0 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c  ue] object..** <
341d0 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64  tr><td>&nbsp;<td
341e0 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70  >&nbsp;<td>&nbsp
341f0 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  ;.** <tr><td><b>
34200 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34210 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  ytes</b><td>&rar
34220 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61 20  r;<td>Size of a 
34230 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46  BLOB.** or a UTF
34240 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 20 69  -8 TEXT result i
34250 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c  n bytes.** <tr><
34260 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f  td><b>sqlite3_co
34270 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62 73  lumn_bytes16&nbs
34280 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20  p;&nbsp;</b>.** 
34290 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b  <td>&rarr;&nbsp;
342a0 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f  &nbsp;<td>Size o
342b0 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54  f UTF-16.** TEXT
342c0 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72   in bytes.** <tr
342d0 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
342e0 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c  column_type</b><
342f0 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65 66  td>&rarr;<td>Def
34300 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70 65  ault.** datatype
34310 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a 2a   of the result.*
34320 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63  * </table></bloc
34330 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62  kquote>.**.** <b
34340 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a  >Details:</b>.**
34350 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
34360 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
34370 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
34380 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
34390 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
343a0 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
343b0 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
343c0 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
343d0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
343e0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
343f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34400 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
34410 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
34420 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
34430 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
34440 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
34450 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34460 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
34470 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
34480 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
34490 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
344a0 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
344b0 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
344c0 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
344d0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
344e0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
344f0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
34500 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
34510 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
34520 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
34530 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
34540 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
34550 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
34560 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
34570 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
34580 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
34590 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
345a0 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
345b0 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
345c0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
345d0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
345e0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
345f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
34600 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
34610 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
34620 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
34630 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
34640 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
34650 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
34660 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
34670 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
34680 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
34690 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
346a0 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
346b0 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
346c0 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
346d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
346e0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
346f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34700 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
34710 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
34720 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
34730 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
34740 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
34750 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
34760 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
34770 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
34780 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
34790 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
347a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
347b0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
347c0 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
347d0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
347e0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
347f0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
34800 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
34810 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
34820 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
34830 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
34840 2a 20 54 68 65 20 66 69 72 73 74 20 73 69 78 20  * The first six 
34850 69 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c 6f  interfaces (_blo
34860 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74  b, _double, _int
34870 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c  , _int64, _text,
34880 20 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a   and _text16).**
34890 20 65 61 63 68 20 72 65 74 75 72 6e 20 74 68 65   each return the
348a0 20 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73 75   value of a resu
348b0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73  lt column in a s
348c0 70 65 63 69 66 69 63 20 64 61 74 61 20 66 6f 72  pecific data for
348d0 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  mat.  If.** the 
348e0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
348f0 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20 69   not initially i
34900 6e 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  n the requested 
34910 66 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61 6d  format (for exam
34920 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71  ple,.** if the q
34930 75 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e 20  uery returns an 
34940 69 6e 74 65 67 65 72 20 62 75 74 20 74 68 65 20  integer but the 
34950 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34960 65 78 74 28 29 20 69 6e 74 65 72 66 61 63 65 0a  ext() interface.
34970 2a 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65 78  ** is used to ex
34980 74 72 61 63 74 20 74 68 65 20 76 61 6c 75 65 29  tract the value)
34990 20 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74   then an automat
349a0 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  ic type conversi
349b0 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
349c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
349d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
349e0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
349f0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
34a00 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
34a10 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
34a20 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
34a30 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
34a40 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
34a50 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
34a60 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
34a70 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
34a80 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
34a90 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
34aa0 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
34ab0 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
34ac0 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20 76  .** The return v
34ad0 61 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33 5f  alue of sqlite3_
34ae0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63 61  column_type() ca
34af0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 63  n be used to dec
34b00 69 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20  ide which.** of 
34b10 74 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e  the first six in
34b20 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 62  terface should b
34b30 65 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63  e used to extrac
34b40 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c  t the column val
34b50 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  ue..** The value
34b60 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
34b70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
34b80 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
34b90 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61  ngful if no.** a
34ba0 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f  utomatic type co
34bb0 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
34bc0 63 63 75 72 72 65 64 20 66 6f 72 20 74 68 65 20  ccurred for the 
34bd0 76 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69 6f  value in questio
34be0 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61 20  n.  .** After a 
34bf0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
34c00 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 63   the result of c
34c10 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
34c20 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
34c30 69 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74 68  is undefined, th
34c40 6f 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20 20  ough harmless.  
34c50 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
34c60 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
34c70 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
34c80 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
34c90 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
34ca0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
34cb0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
34cc0 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
34cd0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 61  t is a BLOB or a
34ce0 20 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74 68   TEXT string, th
34cf0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
34d00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
34d10 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
34d20 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e 74  mn_bytes16() int
34d30 65 72 66 61 63 65 73 20 63 61 6e 20 62 65 20 75  erfaces can be u
34d40 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  sed to determine
34d50 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20   the size.** of 
34d60 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
34d70 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ing..**.** ^If t
34d80 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
34d90 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
34da0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
34db0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34dc0 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
34dd0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
34de0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
34df0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
34e00 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
34e10 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
34e20 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
34e30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34e40 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
34e50 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
34e60 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
34e70 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
34e80 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
34e90 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
34ea0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
34eb0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
34ec0 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
34ed0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
34ee0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
34ef0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
34f00 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
34f10 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
34f20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
34f30 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
34f40 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
34f50 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
34f60 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
34f70 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
34f80 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
34f90 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
34fa0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
34fb0 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
34fc0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
34fd0 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
34fe0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
34ff0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
35000 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
35010 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
35020 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
35030 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
35040 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
35050 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
35060 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
35070 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
35080 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
35090 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
350a0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
350b0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
350c0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
350d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
350e0 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
350f0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
35100 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
35110 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
35120 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
35130 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
35140 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
35150 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
35160 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
35170 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
35180 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35190 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
351a0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
351b0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
351c0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
351d0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
351e0 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
351f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
35200 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
35210 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
35220 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
35230 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
35240 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
35250 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
35260 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
35270 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35280 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
35290 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
352a0 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
352b0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
352c0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
352d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
352e0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
352f0 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
35300 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
35310 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
35320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35330 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
35340 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
35350 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
35360 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
35370 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
35380 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
35390 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
353a0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
353b0 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
353c0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  inter..**.** <b>
353d0 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68  Warning:</b> ^Th
353e0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
353f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
35400 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
35410 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
35420 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35430 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61  e] object.  In a
35440 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65   multithreaded e
35450 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61  nvironment,.** a
35460 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
35470 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
35480 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ct may only be u
35490 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a  sed safely with.
354a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
354b0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
354c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
354d0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
354e0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
354f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
35500 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
35510 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
35520 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
35530 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
35540 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
35550 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
35560 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
35570 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
35580 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
35590 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
355a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
355b0 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68  ytes()], the beh
355c0 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72  avior is not thr
355d0 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63  eadsafe..** Henc
355e0 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  e, the sqlite3_c
355f0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e  olumn_value() in
35600 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f  terface.** is no
35610 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66  rmally only usef
35620 75 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69 6d  ul within the im
35630 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
35640 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  .** [application
35650 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
35660 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74  ctions] or [virt
35670 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74  ual tables], not
35680 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c   within.** top-l
35690 65 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e  evel application
356a0 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   code..**.** The
356b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
356c0 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  may attempt to c
356d0 6f 6e 76 65 72 74 20 74 68 65 20 64 61 74 61 74  onvert the datat
356e0 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ype of the resul
356f0 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70  t..** ^For examp
35700 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
35710 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
35720 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
35730 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
35740 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
35750 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
35760 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
35770 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
35780 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
35790 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
357a0 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
357b0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
357c0 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
357d0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
357e0 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
357f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
35800 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
35810 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
35820 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
35830 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
35840 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
35850 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
35860 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
35870 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
35880 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
35890 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
358a0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
358b0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
358c0 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
358d0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
358e0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
358f0 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
35900 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
35910 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
35920 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
35930 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
35940 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
35950 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
35960 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
35970 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
35980 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
35990 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
359a0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
359b0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
359c0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
359d0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
359e0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
359f0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
35a00 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
35a10 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
35a20 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
35a30 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
35a40 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
35a50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
35a60 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
35a70 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
35a80 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
35a90 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
35aa0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
35ab0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
35ac0 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
35ad0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
35ae0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
35af0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
35b00 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
35b10 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
35b20 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
35b30 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
35b40 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
35b50 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
35b60 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
35b70 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
35b80 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
35b90 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
35ba0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
35bb0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
35bc0 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
35bd0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
35be0 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
35bf0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
35c00 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
35c10 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
35c20 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
35c30 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
35c40 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
35c50 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
35c60 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
35c70 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
35c80 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
35c90 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
35ca0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
35cb0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
35cc0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
35cd0 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
35ce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
35cf0 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
35d00 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
35d10 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
35d20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
35d30 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
35d40 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
35d50 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
35d60 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
35d70 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
35d80 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
35d90 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
35da0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
35db0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
35dc0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
35dd0 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
35de0 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
35df0 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
35e00 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
35e10 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
35e20 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
35e30 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
35e40 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
35e50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
35e60 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
35e70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35e80 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
35e90 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
35ea0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
35eb0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
35ec0 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
35ed0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
35ee0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
35ef0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
35f00 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
35f10 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
35f20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
35f30 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
35f40 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
35f50 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
35f60 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
35f70 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
35f80 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
35f90 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
35fa0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
35fb0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
35fc0 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
35fd0 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
35fe0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
35ff0 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
36000 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
36010 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
36020 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
36030 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
36040 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
36050 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
36060 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
36070 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
36080 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
36090 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
360a0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
360b0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
360c0 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
360d0 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
360e0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
360f0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
36100 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20  afest policy is 
36110 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
36120 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
36130 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
36140 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
36150 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
36160 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36170 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
36180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36190 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
361a0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
361b0 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
361c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
361d0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
361e0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
361f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
36200 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
36210 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36220 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
36230 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
36240 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
36250 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
36260 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
36270 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
36280 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
36290 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
362a0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
362b0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
362c0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
362d0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
362e0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
362f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
36300 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
36310 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
36320 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
36330 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
36340 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
36350 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
36360 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
36370 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
36380 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
36390 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
363a0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
363b0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
363c0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
363d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
363e0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
363f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36400 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
36410 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
36420 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
36430 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
36440 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
36450 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
36460 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
36470 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
36480 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
36490 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
364a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
364b0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
364c0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
364d0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
364e0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
364f0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
36500 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20  ically.  Do not 
36510 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
36520 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
36530 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
36540 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
36550 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36560 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
36570 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
36580 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
36590 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
365a0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
365b0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
365c0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
365d0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
365e0 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
365f0 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
36600 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
36610 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
36620 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
36630 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
36640 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
36650 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
36660 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
36670 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
36680 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
36690 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
366a0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
366b0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
366c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
366d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
366e0 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
366f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
36700 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
36710 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
36720 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
36730 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
36740 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36750 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
36760 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36770 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
36780 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36790 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
367a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
367b0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
367c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
367d0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
367e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
367f0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
36800 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
36810 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
36820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
36830 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
36840 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
36850 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36860 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
36870 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36880 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
36890 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
368a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
368b0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
368c0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
368d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
368e0 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
368f0 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
36900 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
36910 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44  ment Object.** D
36920 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
36930 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
36940 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
36950 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
36960 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
36970 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
36980 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
36990 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
369a0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
369b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
369c0 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
369d0 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
369e0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
369f0 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
36a00 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
36a10 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
36a20 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
36a30 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
36a40 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
36a50 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
36a60 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
36a70 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
36a80 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
36a90 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
36aa0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
36ab0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
36ac0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
36ad0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
36ae0 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
36af0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
36b00 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
36b10 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
36b20 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
36b30 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
36b40 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
36b50 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
36b60 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
36b70 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
36b80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
36b90 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
36ba0 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
36bb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
36bc0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
36bd0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
36be0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
36bf0 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
36c00 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
36c10 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
36c20 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
36c30 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
36c40 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
36c50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
36c60 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
36c70 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
36c80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
36c90 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
36ca0 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
36cb0 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
36cc0 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
36cd0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36ce0 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
36cf0 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
36d00 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
36d10 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
36d20 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
36d30 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
36d40 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
36d50 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
36d60 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
36d70 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
36d80 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
36d90 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
36da0 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
36db0 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
36dc0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
36dd0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
36de0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
36df0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
36e00 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
36e10 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
36e20 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
36e30 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68  e3_stmt.**.** Th
36e40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
36e50 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
36e60 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
36e70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36e80 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
36e90 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
36ea0 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
36eb0 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
36ec0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
36ed0 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
36ee0 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
36ef0 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
36f00 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
36f10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
36f20 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
36f30 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
36f40 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
36f50 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
36f60 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
36f70 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
36f80 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
36f90 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
36fa0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
36fb0 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
36fc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
36fd0 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
36fe0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
36ff0 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
37000 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
37010 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
37020 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
37030 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
37040 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
37050 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
37060 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
37070 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
37080 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
37090 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
370a0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
370b0 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
370c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
370d0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
370e0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
370f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
37100 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
37110 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
37120 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
37130 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
37140 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
37150 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
37160 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
37170 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
37180 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
37190 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
371a0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
371b0 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
371c0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
371d0 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
371e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
371f0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
37200 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
37210 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
37220 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
37230 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
37240 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
37250 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
37260 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
37270 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
37280 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
37290 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
372a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
372b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
372c0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
372d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
372e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
372f0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
37300 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37310 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
37320 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
37330 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
37340 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
37350 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
37360 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
37370 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
37380 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
37390 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
373a0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
373b0 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
373c0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
373d0 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
373e0 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
373f0 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
37400 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
37410 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
37420 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
37430 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
37440 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
37450 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
37460 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
37470 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
37480 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
37490 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
374a0 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
374b0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
374c0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
374d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
374e0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
374f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37500 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
37510 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
37520 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
37530 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
37540 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
37550 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
37560 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
37570 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37580 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
37590 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
375a0 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
375b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
375c0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
375d0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
375e0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
375f0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
37600 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
37610 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
37620 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
37630 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
37640 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
37650 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
37660 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
37670 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
37680 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
37690 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
376a0 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
376b0 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
376c0 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
376d0 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
376e0 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
376f0 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
37700 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
37710 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
37720 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
37730 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
37740 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
37750 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
37760 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
37770 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
37780 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
37790 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
377a0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
377b0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
377c0 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
377d0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
377e0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
377f0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
37800 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
37810 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
37820 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
37830 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
37840 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
37850 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
37860 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
37870 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
37880 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
37890 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
378a0 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
378b0 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
378c0 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
378d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
378e0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
378f0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
37900 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
37910 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
37920 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
37930 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
37940 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
37950 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
37960 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  rs.  The applica
37970 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20  tion should set 
37980 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74  this parameter t
37990 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  o.** [SQLITE_UTF
379a0 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e  16LE] if the fun
379b0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
379c0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a  tion invokes .**
379d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
379e0 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61  text16le()] on a
379f0 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c  n input, or [SQL
37a00 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20  ITE_UTF16BE] if 
37a10 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
37a20 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73  ation invokes [s
37a30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37a40 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16be()] on an i
37a50 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  nput, or.** [SQL
37a60 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73  ITE_UTF16] if [s
37a70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
37a80 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  t16()] is used, 
37a90 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  or [SQLITE_UTF8]
37aa0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20  .** otherwise.  
37ab0 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75  ^The same SQL fu
37ac0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
37ad0 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
37ae0 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a  e times using.**
37af0 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65   different prefe
37b00 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
37b10 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72  ngs, with differ
37b20 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
37b30 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ons for.** each 
37b40 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68  encoding..** ^Wh
37b50 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
37b60 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
37b70 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
37b80 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
37b90 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
37ba0 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
37bb0 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
37bc0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
37bd0 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
37be0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
37bf0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f   parameter may o
37c00 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65  ptionally be ORe
37c10 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
37c20 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a  ETERMINISTIC].**
37c30 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20   to signal that 
37c40 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  the function wil
37c50 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
37c60 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20  the same result 
37c70 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  given.** the sam
37c80 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20  e inputs within 
37c90 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
37ca0 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51  tement.  Most SQ
37cb0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a  L functions are.
37cc0 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ** deterministic
37cd0 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  .  The built-in 
37ce0 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66  [random()] SQL f
37cf0 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78  unction is an ex
37d00 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75  ample of a.** fu
37d10 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e  nction that is n
37d20 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ot deterministic
37d30 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75  .  The SQLite qu
37d40 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61  ery planner is a
37d50 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72  ble to.** perfor
37d60 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74  m additional opt
37d70 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65  imizations on de
37d80 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63  terministic func
37d90 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a  tions, so use.**
37da0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
37db0 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66  DETERMINISTIC] f
37dc0 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  lag is recommend
37dd0 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c  ed where possibl
37de0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  e..**.** ^(The f
37df0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
37e00 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
37e10 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
37e20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
37e30 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
37e40 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
37e50 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
37e60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
37e70 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
37e80 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
37e90 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
37ea0 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
37eb0 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
37ec0 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
37ed0 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
37ee0 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
37ef0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
37f00 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
37f10 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
37f20 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
37f30 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
37f40 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
37f50 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
37f60 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
37f70 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
37f80 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
37f90 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
37fa0 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
37fb0 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
37fc0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
37fd0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
37fe0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
37ff0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
38000 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
38010 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
38020 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
38030 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
38040 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
38050 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
38060 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
38070 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
38080 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
38090 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
380a0 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
380b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
380c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
380d0 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
380e0 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
380f0 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
38100 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
38110 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
38120 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
38130 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
38140 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
38150 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
38160 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
38170 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
38180 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
38190 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
381a0 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
381b0 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
381c0 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
381d0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
381e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
381f0 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
38200 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
38210 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
38220 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
38230 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
38240 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
38250 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
38260 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
38270 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
38280 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
38290 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
382a0 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
382b0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
382c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
382d0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
382e0 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
382f0 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
38300 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
38310 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
38320 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
38330 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
38340 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
38350 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
38360 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
38370 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
38380 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
38390 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
383a0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
383b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
383c0 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
383d0 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
383e0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
383f0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
38400 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
38410 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
38420 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
38430 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
38440 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
38450 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
38460 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
38470 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
38480 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
38490 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
384a0 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
384b0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
384c0 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
384d0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
384e0 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
384f0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
38500 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
38510 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
38520 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
38530 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
38540 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
38550 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
38560 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
38570 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
38580 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
38590 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
385a0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
385b0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
385c0 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
385d0 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
385e0 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
385f0 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
38600 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
38610 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
38620 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
38630 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
38640 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
38650 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
38660 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
38670 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
38680 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
38690 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
386a0 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
386b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
386c0 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
386d0 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
386e0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
386f0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
38700 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
38710 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ing..*/.int sqli
38720 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
38730 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
38740 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
38750 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
38760 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
38770 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
3