/ Hex Artifact Content
Login

Artifact 1c803f1655c1f527eda3d357b0303e313cc77431b28baa00252421ca7f8a41c0:


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 41 4e 54 4f 50 45 4e 5f 44  QLITE_CANTOPEN_D
5b80: 49 52 54 59 57 41 4c 20 20 20 20 20 20 20 28 53  IRTYWAL       (S
5b90: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5ba0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5bb0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5bc0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5bd0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
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 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
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 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<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 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
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 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<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 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
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 33 3c 3c 38 29 29 0a  DONLY | (3<<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 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
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 34 3c 3c 38 29  EADONLY | (4<<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 43 41 4e 54 49 4e  _READONLY_CANTIN
5d10: 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  IT       (SQLITE
5d20: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c  _READONLY | (5<<
5d30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d40: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45  TE_READONLY_DIRE
5d50: 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49  CTORY      (SQLI
5d60: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36  TE_READONLY | (6
5d70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5d80: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5d90: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5da0: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5db0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5dc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5dd0: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5de0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5df0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5e00: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5e10: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
5e20: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5e30: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
5e40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5e50: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5e60: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5e70: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5e80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e90: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5ea0: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5eb0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5ec0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5ed0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5ee0: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5ef0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5f00: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5f10: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5f20: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5f30: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5f40: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5f60: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5f80: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5f90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fa0: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5fb0: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
5fc0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
5fd0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5fe0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
5ff0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
6000: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
6010: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
6020: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
6030: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
6040: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
6050: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
6060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6070: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
6080: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
6090: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
60a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
60b0: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
60c0: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
60d0: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
60e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
60f0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
6100: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
6110: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
6120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
6130: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
6140: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
6150: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  H | (1<<8)).#def
6160: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f  ine SQLITE_OK_LO
6170: 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20  AD_PERMANENTLY  
6180: 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20     (SQLITE_OK | 
6190: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
61a0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
61b0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
61c0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
61d0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
61e0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
61f0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
6200: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
6210: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
6220: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
6230: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
6240: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
6250: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6260: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
6270: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6280: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
6290: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
62a0: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
62b0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
62c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
62d0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
62e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
62f0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
6300: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6310: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6320: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
6330: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6340: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
6350: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6360: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6370: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
6380: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
6390: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
63a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63b0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
63c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
63d0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
63e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
63f0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
6400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6410: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
6420: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6430: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
6440: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6450: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
6460: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6470: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6480: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
6490: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
64a0: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
64b0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
64c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
64d0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
64e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
64f0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6500: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6510: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
6520: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6530: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6540: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6550: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
6560: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
6570: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6580: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6590: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
65a0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
65b0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
65c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65d0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
65e0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
65f0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6600: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6610: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
6620: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6630: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6640: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6650: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6660: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6670: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6680: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6690: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
66a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
66b0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
66c0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
66d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
66e0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
66f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
6700: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6710: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6720: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6730: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6740: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6750: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6760: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6770: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6780: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
6790: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
67a0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
67b0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
67c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
67d0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
67e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
67f0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6810: 45 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54 45  E_OPEN_FILEPROTE
6820: 43 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20 20  CTION_MASK      
6830: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6840: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 37             0x007
6850: 30 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72 76  00000../* Reserv
6860: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
6870: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6880: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
6890: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
68a0: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
68b0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
68c0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
68d0: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
68e0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
68f0: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
6900: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
6910: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
6920: 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a  ctor of these.**
6930: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
6940: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
6950: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
6960: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
6970: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
6980: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
6990: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
69a0: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
69b0: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
69c0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
69d0: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
69e0: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
69f0: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
6a00: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
6a10: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6a20: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
6a30: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
6a40: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
6a50: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
6a60: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
6a70: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
6a80: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
6a90: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
6aa0: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
6ab0: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
6ac0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6ad0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
6ae0: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
6af0: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
6b00: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
6b10: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
6b20: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
6b30: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
6b40: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
6b50: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
6b60: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
6b70: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
6b80: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6b90: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
6ba0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
6bb0: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
6bc0: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
6bd0: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
6be0: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
6bf0: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
6c00: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6c10: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
6c20: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6c30: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
6c40: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
6c50: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
6c60: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
6c70: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
6c80: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
6c90: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
6ca0: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
6cb0: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
6cc0: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
6cd0: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
6ce0: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
6cf0: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
6d00: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
6d10: 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
6d20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6d30: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6d40: 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69  PEN.** flag indi
6d50: 63 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c  cates that a fil
6d60: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
6d70: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
6d80: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
6d90: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
6da0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
6db0: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
6dc0: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
6dd0: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6de0: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6df0: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6e00: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6e10: 76 69 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  vileges..**.** T
6e20: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6e30: 42 41 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f  BATCH_ATOMIC pro
6e40: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6e50: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a   the underlying.
6e60: 2a 2a 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75  ** filesystem su
6e70: 70 70 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c  pports doing mul
6e80: 74 69 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72  tiple write oper
6e90: 61 74 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c  ations atomicall
6ea0: 79 20 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20  y when those.** 
6eb0: 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  write operations
6ec0: 20 61 72 65 20 62 72 61 63 6b 65 74 65 64 20 62   are bracketed b
6ed0: 79 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  y [SQLITE_FCNTL_
6ee0: 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49  BEGIN_ATOMIC_WRI
6ef0: 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49  TE] and.** [SQLI
6f00: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
6f10: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a  ATOMIC_WRITE]..*
6f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6f30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
6f40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6f50: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
6f60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6f70: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20  OMIC512         
6f80: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
6f90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6fa0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
6fb0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6fc0: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
6fd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6fe0: 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC2K            
6ff0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
7000: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7010: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
7020: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7030: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
7040: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7050: 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  8K              
7060: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
7070: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7080: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
7090: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
70a0: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
70b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
70c0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
70d0: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
70e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
70f0: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20  TOMIC64K        
7100: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
7110: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7120: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
7130: 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30  D            0x0
7140: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
7150: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
7160: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20  UENTIAL         
7170: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
7180: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7190: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
71a0: 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30  WHEN_OPEN  0x000
71b0: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
71c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
71d0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
71e0: 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65    0x00001000.#de
71f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
7200: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20  P_IMMUTABLE     
7210: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32           0x00002
7220: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
7230: 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41  TE_IOCAP_BATCH_A
7240: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
7250: 30 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a  0x00004000../*.*
7260: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
7270: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
7280: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
7290: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
72a0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
72b0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
72c0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
72d0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
72e0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
72f0: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
7300: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
7310: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
7320: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
7330: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
7340: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
7350: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
7360: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
7370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
7380: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
7390: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
73a0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
73b0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
73c0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
73d0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
73e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
73f0: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
7400: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
7410: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
7420: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
7430: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
7440: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7450: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
7460: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
7470: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
7480: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
7490: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
74a0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
74b0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
74c0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
74d0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
74e0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
74f0: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
7500: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
7510: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
7520: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
7530: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
7540: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
7550: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
7560: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
7570: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
7580: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
7590: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
75a0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
75b0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
75c0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
75d0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
75e0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
75f0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
7600: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
7610: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
7620: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
7630: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
7640: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
7650: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
7660: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
7670: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
7680: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
7690: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
76a0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
76b0: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
76c0: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
76d0: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
76e0: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
76f0: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
7700: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
7710: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
7720: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
7730: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
7740: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
7750: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
7760: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
7770: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
7780: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
7790: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
77a0: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
77b0: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
77c0: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
77d0: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
77e0: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
77f0: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
7800: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
7810: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
7820: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
7830: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
7840: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
7850: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
7860: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7870: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7880: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
7890: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
78a0: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
78b0: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
78c0: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
78d0: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
78e0: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
78f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7900: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
7910: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
7920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7930: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
7940: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
7950: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7960: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
7970: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7980: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
7990: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
79a0: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
79b0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
79c0: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
79d0: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
79e0: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
79f0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
7a00: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
7a10: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
7a20: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
7a30: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
7a40: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
7a50: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
7a60: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
7a70: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
7a80: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
7a90: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
7aa0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
7ab0: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
7ac0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
7ad0: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
7ae0: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
7af0: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
7b00: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
7b10: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
7b20: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
7b30: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
7b40: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
7b50: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
7b60: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
7b70: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
7b80: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
7b90: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
7ba0: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
7bb0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
7bc0: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
7bd0: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
7be0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
7bf0: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
7c00: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
7c10: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7c20: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
7c30: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7c40: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
7c50: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
7c60: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
7c70: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7c80: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
7c90: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
7ca0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
7cb0: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
7cc0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
7cd0: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
7ce0: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
7cf0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
7d00: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
7d10: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
7d20: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7d30: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
7d40: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69  .** If the [sqli
7d50: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
7d60: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73  ethod sets the s
7d70: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7d80: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a  hods element .**
7d90: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   to a non-NULL p
7da0: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ointer, then the
7db0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7dc0: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f  ods.xClose metho
7dd0: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f  d.** may be invo
7de0: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20  ked even if the 
7df0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7e00: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61  en] reported tha
7e10: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68  t it failed.  Th
7e20: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f  e.** only way to
7e30: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20   prevent a call 
7e40: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77  to xClose follow
7e50: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71  ing a failed [sq
7e60: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7e70: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b  .** is for the [
7e80: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7e90: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71  n] to set the sq
7ea0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
7eb0: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74  ods element.** t
7ec0: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o NULL..**.** Th
7ed0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
7ee0: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
7ef0: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
7f00: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a  SYNC_NORMAL] or.
7f10: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ** [SQLITE_SYNC_
7f20: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73  FULL].  The firs
7f30: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20  t choice is the 
7f40: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a  normal fsync()..
7f50: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68  ** The second ch
7f60: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53  oice is a Mac OS
7f70: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7f80: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  c.  The [SQLITE_
7f90: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a  SYNC_DATAONLY].*
7fa0: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  * flag may be OR
7fb0: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74  ed in to indicat
7fc0: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
7fd0: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
7fe0: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  .** and not its 
7ff0: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
8000: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20  e synced..**.** 
8010: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
8020: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
8030: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
8040: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
8050: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
8060: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
8070: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
8080: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
8090: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
80a0: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
80b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
80c0: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
80d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
80e0: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
80f0: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
8100: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
8110: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
8120: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
8130: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52  ..** The xCheckR
8140: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
8150: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74  thod checks whet
8160: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65  her any database
8170: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20   connection,.** 
8180: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70  either in this p
8190: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
81a0: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
81b0: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45   is holding a RE
81c0: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
81d0: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
81e0: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
81f0: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
8200: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
8210: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
8220: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65   false otherwise
8230: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c  ..**.** The xFil
8240: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f  eControl() metho
8250: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69  d is a generic i
8260: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c  nterface that al
8270: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56  lows custom.** V
8280: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
8290: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63  ns to directly c
82a0: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66  ontrol an open f
82b0: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
82c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
82d0: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
82e0: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ace.  The second
82f0: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69   "op" argument i
8300: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  s an.** integer 
8310: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69  opcode.  The thi
8320: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
8330: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72   generic pointer
8340: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20   intended to.** 
8350: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63  point to a struc
8360: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f  ture that may co
8370: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20  ntain arguments 
8380: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63  or space in whic
8390: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65  h to.** write re
83a0: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f  turn values.  Po
83b0: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72  tential uses for
83c0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
83d0: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63  might be.** func
83e0: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20  tions to enable 
83f0: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77  blocking locks w
8400: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f  ith timeouts, to
8410: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c   change the.** l
8420: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20  ocking strategy 
8430: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20  (for example to 
8440: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63  use dot-file loc
8450: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a  ks), to inquire.
8460: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61  ** about the sta
8470: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f  tus of a lock, o
8480: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65  r to break stale
8490: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c   locks.  The SQL
84a0: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65  ite.** core rese
84b0: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73  rves all opcodes
84c0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66   less than 100 f
84d0: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a  or its own use..
84e0: 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72  ** A [file contr
84f0: 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73  ol opcodes | lis
8500: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
8510: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
8520: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
8530: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
8540: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
8550: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
8560: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
8570: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
8580: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
8590: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
85a0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
85b0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
85c0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
85d0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
85e0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
85f0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
8600: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
8610: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
8620: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
8630: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
8640: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
8650: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
8660: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
8670: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
8680: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
8690: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
86a0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
86b0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
86c0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
86d0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
86e0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
86f0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
8700: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
8710: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
8720: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
8730: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
8740: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
8750: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
8760: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8770: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
8780: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8790: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
87a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
87b0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
87c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
87d0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
87e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
87f0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
8800: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8810: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
8820: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8830: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
8840: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8850: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
8860: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8870: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
8880: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
8890: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
88a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
88b0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
88c0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
88d0: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
88e0: 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c  WHEN_OPEN].** <l
88f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8900: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
8910: 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  RITE].** <li> [S
8920: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
8930: 54 41 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TABLE].** <li> [
8940: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54  SQLITE_IOCAP_BAT
8950: 43 48 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f  CH_ATOMIC].** </
8960: 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  ul>.**.** The SQ
8970: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8980: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
8990: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
89a0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
89b0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
89c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
89d0: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
89e0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
89f0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
8a00: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
8a10: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
8a20: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
8a30: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
8a40: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
8a50: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
8a60: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
8a70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
8a80: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
8a90: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
8aa0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
8ab0: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
8ac0: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
8ad0: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
8ae0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
8af0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
8b00: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
8b10: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
8b20: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
8b30: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
8b40: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
8b50: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
8b60: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
8b70: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
8b80: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
8b90: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
8ba0: 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28  .**.** If xRead(
8bb0: 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
8bc0: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
8bd0: 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66  D it must also f
8be0: 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e  ill.** in the un
8bf0: 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66  read portions of
8c00: 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68   the buffer with
8c10: 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74   zeros.  A VFS t
8c20: 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20  hat.** fails to 
8c30: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20  zero-fill short 
8c40: 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d  reads might seem
8c50: 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76   to work.  Howev
8c60: 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74  er,.** failure t
8c70: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
8c80: 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65  t reads will eve
8c90: 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a  ntually lead to.
8ca0: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72  ** database corr
8cb0: 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  uption..*/.typed
8cc0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
8cd0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c  3_io_methods sql
8ce0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b  ite3_io_methods;
8cf0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
8d00: 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69  io_methods {.  i
8d10: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69  nt iVersion;.  i
8d20: 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c  nt (*xClose)(sql
8d30: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8d40: 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69  nt (*xRead)(sqli
8d50: 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a  te3_file*, void*
8d60: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
8d70: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
8d80: 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65  ;.  int (*xWrite
8d90: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8da0: 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
8db0: 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f  t iAmt, sqlite3_
8dc0: 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20  int64 iOfst);.  
8dd0: 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29  int (*xTruncate)
8de0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8df0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69  sqlite3_int64 si
8e00: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79  ze);.  int (*xSy
8e10: 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  nc)(sqlite3_file
8e20: 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20  *, int flags);. 
8e30: 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65   int (*xFileSize
8e40: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8e50: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
8e60: 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a  pSize);.  int (*
8e70: 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  xLock)(sqlite3_f
8e80: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8e90: 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c  t (*xUnlock)(sql
8ea0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8eb0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b  ;.  int (*xCheck
8ec0: 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71  ReservedLock)(sq
8ed0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8ee0: 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
8ef0: 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  t (*xFileControl
8f00: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8f10: 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70   int op, void *p
8f20: 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Arg);.  int (*xS
8f30: 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74  ectorSize)(sqlit
8f40: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8f50: 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63   (*xDeviceCharac
8f60: 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74  teristics)(sqlit
8f70: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20  e3_file*);.  /* 
8f80: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8f90: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8fa0: 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28  ion 1 */.  int (
8fb0: 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65  *xShmMap)(sqlite
8fc0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67  3_file*, int iPg
8fd0: 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c  , int pgsz, int,
8fe0: 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a   void volatile**
8ff0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c  );.  int (*xShmL
9000: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
9010: 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20  e*, int offset, 
9020: 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73  int n, int flags
9030: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d  );.  void (*xShm
9040: 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33  Barrier)(sqlite3
9050: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  _file*);.  int (
9060: 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69  *xShmUnmap)(sqli
9070: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64  te3_file*, int d
9080: 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a  eleteFlag);.  /*
9090: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
90a0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
90b0: 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20  sion 2 */.  int 
90c0: 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65  (*xFetch)(sqlite
90d0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
90e0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e  _int64 iOfst, in
90f0: 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70  t iAmt, void **p
9100: 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66  p);.  int (*xUnf
9110: 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69  etch)(sqlite3_fi
9120: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
9130: 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a  64 iOfst, void *
9140: 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  p);.  /* Methods
9150: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
9160: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a   for version 3 *
9170: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
9180: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
9190: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
91a0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
91b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
91c0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
91d0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
91e0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c  * KEYWORDS: {fil
91f0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
9200: 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  s} {file control
9210: 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54   opcode}.**.** T
9220: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
9230: 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64  stants are opcod
9240: 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65  es for the xFile
9250: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a  Control method.*
9260: 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
9270: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
9280: 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65  ject and for the
9290: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
92a0: 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74  ontrol()].** int
92b0: 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75  erface..**.** <u
92c0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  l>.** <li>[[SQLI
92d0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
92e0: 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  TE]].** The [SQL
92f0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
9300: 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ATE] opcode is u
9310: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
9320: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
9330: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
9340: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
9350: 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63  d to write the c
9360: 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a  urrent state of.
9370: 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65  ** the lock (one
9380: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   of [SQLITE_LOCK
9390: 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _NONE], [SQLITE_
93a0: 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a  LOCK_SHARED],.**
93b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
93c0: 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45  SERVED], [SQLITE
93d0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
93e0: 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  or [SQLITE_LOCK_
93f0: 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69  EXCLUSIVE]).** i
9400: 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74  nto an integer t
9410: 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67  hat the pArg arg
9420: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e  ument points to.
9430: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
9440: 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69  .** is used duri
9450: 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69  ng testing and i
9460: 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
9470: 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   when the SQLITE
9480: 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65  _TEST.** compile
9490: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
94a0: 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  used..**.** <li>
94b0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
94c0: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
94d0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
94e0: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
94f0: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
9500: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
9510: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
9520: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
9530: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9540: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
9550: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
9560: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
9570: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
9580: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
9590: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
95a0: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
95b0: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
95c0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
95d0: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
95e0: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
95f0: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
9600: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
9610: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
9620: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
9630: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
9640: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
9650: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9660: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
9670: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
9680: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
9690: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
96a0: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
96b0: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
96c0: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
96d0: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
96e0: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
96f0: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
9700: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
9710: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
9720: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
9730: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9740: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
9750: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
9760: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
9770: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
9780: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
9790: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
97a0: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
97b0: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
97c0: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
97d0: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
97e0: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
97f0: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
9800: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
9810: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
9820: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
9830: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
9840: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
9850: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9860: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
9870: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
9880: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
9890: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
98a0: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
98b0: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
98c0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
98d0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
98e0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
98f0: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
9900: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
9910: 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c  .  See also [SQL
9920: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
9930: 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a  L_POINTER]..**.*
9940: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9950: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
9960: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
9970: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
9980: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63  NAL_POINTER] opc
9990: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f  ode is used to o
99a0: 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a  btain a pointer.
99b0: 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
99c0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
99d0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
99e0: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  the journal file
99f0: 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20   (either.** the 
9a00: 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61  [rollback journa
9a10: 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65  l] or the [write
9a20: 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72  -ahead log]) for
9a30: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
9a40: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
9a50: 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20  tion.  See also 
9a60: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9a70: 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a  LE_POINTER]..**.
9a80: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9a90: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
9aa0: 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65  ED]].** No longe
9ab0: 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20  r in use..**.** 
9ac0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9ad0: 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65  TL_SYNC]].** The
9ae0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
9af0: 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  YNC] opcode is g
9b00: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9b10: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e  lly by SQLite an
9b20: 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65  d.** sent to the
9b30: 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79   VFS immediately
9b40: 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e   before the xSyn
9b50: 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  c method is invo
9b60: 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61  ked on a.** data
9b70: 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69  base file descri
9b80: 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65  ptor. Or, if the
9b90: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
9ba0: 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a   not invoked .**
9bb0: 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65   because the use
9bc0: 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64  r has configured
9bd0: 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a   SQLite with .**
9be0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
9bf0: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79  nous | PRAGMA sy
9c00: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69  nchronous=OFF] i
9c10: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20  t is invoked in 
9c20: 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65  place .** of the
9c30: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49   xSync method. I
9c40: 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68  n most cases, th
9c50: 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
9c60: 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a  nt passed with.*
9c70: 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  * this file-cont
9c80: 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77  rol is NULL. How
9c90: 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74  ever, if the dat
9ca0: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65  abase file is be
9cb0: 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73  ing synced.** as
9cc0: 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69   part of a multi
9cd0: 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74  -database commit
9ce0: 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70  , the argument p
9cf0: 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74  oints to a nul-t
9d00: 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
9d10: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
9d20: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  he transactions 
9d30: 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66  master-journal f
9d40: 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20  ile name. VFSes 
9d50: 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20  that .** do not 
9d60: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9d70: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
9d80: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
9d90: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
9da0: 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  s .** should not
9db0: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
9dc0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
9dd0: 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ith this opcode 
9de0: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
9df0: 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20  .** disrupt the 
9e00: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
9e10: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
9e20: 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  es that do requi
9e30: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
9e40: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9e50: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9e60: 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  O]].** The [SQLI
9e70: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
9e80: 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65  PHASETWO] opcode
9e90: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9ea0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
9eb0: 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74  te.** and sent t
9ec0: 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20  o the VFS after 
9ed0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61  a transaction ha
9ee0: 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64  s been committed
9ef0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20   immediately.** 
9f00: 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64  but before the d
9f10: 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63  atabase is unloc
9f20: 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20  ked. VFSes that 
9f30: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
9f40: 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c   signal.** shoul
9f50: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9f60: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9f70: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
9f80: 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b  ld not call.** [
9f90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9fa0: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9fb0: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
9fc0: 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74  g so may disrupt
9fd0: 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69   the .** operati
9fe0: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
9ff0: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
a000: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
a010: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
a020: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
a030: 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e  _AV_RETRY]].** ^
a040: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a050: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
a060: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a070: 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75   to configure au
a080: 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79  tomatic.** retry
a090: 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65   counts and inte
a0a0: 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69  rvals for certai
a0b0: 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61  n disk I/O opera
a0c0: 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a  tions for the.**
a0d0: 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69   windows [VFS] i
a0e0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
a0f0: 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e  de robustness in
a100: 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   the presence of
a110: 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70  .** anti-virus p
a120: 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66  rograms.  By def
a130: 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77  ault, the window
a140: 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79  s VFS will retry
a150: 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66   file read,.** f
a160: 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66  ile write, and f
a170: 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61  ile delete opera
a180: 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74  tions up to 10 t
a190: 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c  imes, with a del
a1a0: 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c  ay.** of 25 mill
a1b0: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20  iseconds before 
a1c0: 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20  the first retry 
a1d0: 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c  and with the del
a1e0: 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a  ay increasing.**
a1f0: 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61   by an additiona
a200: 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  l 25 millisecond
a210: 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73  s with each subs
a220: 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54  equent retry.  T
a230: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c  his.** opcode al
a240: 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76  lows these two v
a250: 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65  alues (10 retrie
a260: 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65  s and 25 millise
a270: 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a  conds of delay).
a280: 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65  ** to be adjuste
a290: 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61  d.  The values a
a2a0: 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61  re changed for a
a2b0: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ll database conn
a2c0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69  ections.** withi
a2d0: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
a2e0: 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  ss.  The argumen
a2f0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
a300: 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  o an array of tw
a310: 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68  o.** integers wh
a320: 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e  ere the first in
a330: 74 65 67 65 72 20 69 73 20 74 68 65 20 6e 65 77  teger is the new
a340: 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64   retry count and
a350: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69   the second.** i
a360: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65  nteger is the de
a370: 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20  lay.  If either 
a380: 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74  integer is negat
a390: 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65  ive, then the se
a3a0: 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20  tting.** is not 
a3b0: 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74  changed but inst
a3c0: 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61  ead the prior va
a3d0: 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74  lue of that sett
a3e0: 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  ing is written.*
a3f0: 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79  * into the array
a400: 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67   entry, allowing
a410: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74   the current ret
a420: 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62  ry settings to b
a430: 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65  e.** interrogate
a440: 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20  d.  The zDbName 
a450: 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e  parameter is ign
a460: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ored..**.** <li>
a470: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a480: 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20  ERSIST_WAL]].** 
a490: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a4a0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20  TL_PERSIST_WAL] 
a4b0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
a4c0: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
a4d0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
a4e0: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68   [WAL | Write Ah
a4f0: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67  ead Log] setting
a500: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
a510: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20  he auxiliary.** 
a520: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20  write ahead log 
a530: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
a540: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72  y files used for
a550: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
a560: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f  trol.** are auto
a570: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
a580: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73  d when the lates
a590: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  t connection to 
a5a0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
a5b0: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67  closes.  Setting
a5c0: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
a5d0: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73  mode causes thos
a5e0: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69  e files to persi
a5f0: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73  st after.** clos
a600: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74  e.  Persisting t
a610: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66  he files is usef
a620: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72  ul when other pr
a630: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20  ocesses that do 
a640: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74  not.** have writ
a650: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20  e permission on 
a660: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f  the directory co
a670: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74  ntaining the dat
a680: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a  abase file want.
a690: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64  ** to read the d
a6a0: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73  atabase file, as
a6b0: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61   the WAL and sha
a6c0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
a6d0: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69   must exist.** i
a6e0: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20  n order for the 
a6f0: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  database to be r
a700: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f  eadable.  The fo
a710: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a720: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a730: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a740: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a750: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a760: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a770: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a780: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a790: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
a7a0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
a7b0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  ble persistent.*
a7c0: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20  * WAL mode.  If 
a7d0: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a7e0: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a7f0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a800: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41  he current.** WA
a810: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65  L persistence se
a820: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
a830: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a840: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a850: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a860: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a870: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a880: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
a890: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
a8a0: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
a8b0: 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65  t "powersafe-ove
a8c0: 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57  rwrite" or "PSOW
a8d0: 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20  " setting.  The 
a8e0: 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20  PSOW setting.** 
a8f0: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b  determines the [
a900: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
a910: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a920: 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20  ] bit of the.** 
a930: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
a940: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20  istics methods. 
a950: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
a960: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
a970: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a980: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
a990: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
a9a0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
a9b0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
a9c0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
a9d0: 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  isable zero-dama
a9e0: 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  ge mode or 1 to 
a9f0: 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  enable zero-dama
aa00: 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20  ge.** mode.  If 
aa10: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
aa20: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
aa30: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
aa40: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65  he current.** ze
aa50: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73  ro-damage mode s
aa60: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
aa70: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
aa80: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
aa90: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
aaa0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  TL_OVERWRITE] op
aab0: 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  code is invoked 
aac0: 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20  by SQLite after 
aad0: 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69  opening.** a wri
aae0: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  te transaction t
aaf0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c  o indicate that,
ab00: 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f   unless it is ro
ab10: 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f  lled back for so
ab20: 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68  me.** reason, th
ab30: 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73  e entire databas
ab40: 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f  e file will be o
ab50: 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
ab60: 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72  e current .** tr
ab70: 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20  ansaction. This 
ab80: 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55  is used by VACUU
ab90: 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  M operations..**
aba0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
abb0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d  _FCNTL_VFSNAME]]
abc0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
abd0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20  _FCNTL_VFSNAME] 
abe0: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
abf0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
ac00: 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c   names of.** all
ac10: 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20   [VFSes] in the 
ac20: 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20  VFS stack.  The 
ac30: 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c  names are of all
ac40: 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74   VFS shims and t
ac50: 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74  he.** final bott
ac60: 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65  om-level VFS are
ac70: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
ac80: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
ac90: 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
aca0: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68  malloc()] and th
acb0: 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72  e result is stor
acc0: 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20  ed in the char* 
acd0: 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74  variable.** that
ace0: 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
acf0: 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65  meter of [sqlite
ad00: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
ad10: 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20  ] points to..** 
ad20: 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65  The caller is re
ad30: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72  sponsible for fr
ad40: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79  eeing the memory
ad50: 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20   when done.  As 
ad60: 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65  with.** all file
ad70: 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73  -control actions
ad80: 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75  , there is no gu
ad90: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69  arantee that thi
ada0: 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a  s will actually.
adb0: 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20  ** do anything. 
adc0: 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20   Callers should 
add0: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63  initialize the c
ade0: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f  har* variable to
adf0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
ae00: 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20  er in case this 
ae10: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
ae20: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e  not implemented.
ae30: 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74    This file-cont
ae40: 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64  rol.** is intend
ae50: 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69  ed for diagnosti
ae60: 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  c use only..**.*
ae70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ae80: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
ae90: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
aea0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
aeb0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e  NTER] opcode fin
aec0: 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ds a pointer to 
aed0: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a  the top-level.**
aee0: 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74   [VFSes] current
aef0: 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68  ly in use.  ^(Th
af00: 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a  e argument X in.
af10: 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  ** sqlite3_file_
af20: 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54  control(db,SQLIT
af30: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
af40: 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a  TER,X) must be.*
af50: 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69  * of type "[sqli
af60: 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54  te3_vfs] **".  T
af70: 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c  his opcodes will
af80: 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20   set *X.** to a 
af90: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74  pointer to the t
afa0: 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a  op-level VFS.)^.
afb0: 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61  ** ^When there a
afc0: 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20  re multiple VFS 
afd0: 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61  shims in the sta
afe0: 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ck, this opcode 
aff0: 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70  finds the.** upp
b000: 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c  er-most shim onl
b010: 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  y..**.** <li>[[S
b020: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b030: 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65  MA]].** ^Wheneve
b040: 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  r a [PRAGMA] sta
b050: 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64  tement is parsed
b060: 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e  , an [SQLITE_FCN
b070: 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66  TL_PRAGMA] .** f
b080: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73  ile control is s
b090: 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20  ent to the open 
b0a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
b0b0: 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64  bject correspond
b0c0: 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61  ing.** to the da
b0d0: 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77  tabase file to w
b0e0: 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20  hich the pragma 
b0f0: 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73  statement refers
b100: 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a  . ^The argument.
b110: 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54  ** to the [SQLIT
b120: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b130: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b140: 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70  an array of.** p
b150: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
b160: 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77  gs (char**) in w
b170: 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20  hich the second 
b180: 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  element of the a
b190: 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e  rray.** is the n
b1a0: 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ame of the pragm
b1b0: 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20  a and the third 
b1c0: 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61  element is the a
b1d0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
b1e0: 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c  * pragma or NULL
b1f0: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68   if the pragma h
b200: 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20  as no argument. 
b210: 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f   ^The handler fo
b220: 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r an.** [SQLITE_
b230: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
b240: 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f  le control can o
b250: 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74  ptionally make t
b260: 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74  he first element
b270: 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a  .** of the char*
b280: 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  * argument point
b290: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74   to a string obt
b2a0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
b2b0: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a  te3_mprintf()].*
b2c0: 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c  * or the equival
b2d0: 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72  ent and that str
b2e0: 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20  ing will become 
b2f0: 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68  the result of th
b300: 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74  e pragma or.** t
b310: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
b320: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66   if the pragma f
b330: 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a  ails. ^If the.**
b340: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b350: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
b360: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
b370: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
b380: 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b  hen normal .** [
b390: 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69  PRAGMA] processi
b3a0: 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e  ng continues.  ^
b3b0: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
b3c0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
b3d0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
b3e0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
b3f0: 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65  , then the parse
b400: 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  r assumes that t
b410: 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61  he.** VFS has ha
b420: 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41  ndled the PRAGMA
b430: 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20   itself and the 
b440: 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73  parser generates
b450: 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70   a no-op.** prep
b460: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
b470: 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20  f result string 
b480: 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74  is NULL, or that
b490: 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a   returns a copy.
b4a0: 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
b4b0: 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 20 73   string if the s
b4c0: 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c  tring is non-NUL
b4d0: 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  L..** ^If the [S
b4e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b4f0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
b500: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
b510: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65  result code othe
b520: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
b530: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f  K] or [SQLITE_NO
b540: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65  TFOUND], that me
b550: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ans.** that the 
b560: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  VFS encountered 
b570: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68  an error while h
b580: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41  andling the [PRA
b590: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  GMA] and the.** 
b5a0: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74  compilation of t
b5b0: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20  he PRAGMA fails 
b5c0: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
b5d0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
b5e0: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
b5f0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72  le control occur
b600: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69  s at the beginni
b610: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61  ng of pragma sta
b620: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20  tement analysis 
b630: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20  and so.** it is 
b640: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65  able to override
b650: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d   built-in [PRAGM
b660: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  A] statements..*
b670: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b680: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
b690: 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  LER]].** ^The [S
b6a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
b6b0: 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65  HANDLER].** file
b6c0: 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20  -control may be 
b6d0: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
b6e0: 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  e on the databas
b6f0: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a  e file handle.**
b700: 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69   shortly after i
b710: 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f  t is opened in o
b720: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
b730: 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74  a custom VFS wit
b740: 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74  h access.** to t
b750: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62  he connections b
b760: 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
b770: 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65  back. The argume
b780: 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76  nt is of type (v
b790: 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20  oid **).** - an 
b7a0: 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f  array of two (vo
b7b0: 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68  id *) values. Th
b7c0: 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29  e first (void *)
b7d0: 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73   actually points
b7e0: 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  .** to a functio
b7f0: 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28  n of type (int (
b800: 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20  *)(void *)). In 
b810: 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20  order to invoke 
b820: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  the connections.
b830: 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c  ** busy-handler,
b840: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   this function s
b850: 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64  hould be invoked
b860: 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64   with the second
b870: 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20   (void *) in.** 
b880: 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65  the array as the
b890: 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
b8a0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f  If it returns no
b8b0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
b8c0: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68   operation.** sh
b8d0: 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e  ould be retried.
b8e0: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a   If it returns z
b8f0: 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20  ero, the custom 
b900: 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64  VFS should aband
b910: 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  on the.** curren
b920: 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  t operation..**.
b930: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b940: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
b950: 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61  ME]].** ^Applica
b960: 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20  tion can invoke 
b970: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b980: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20  L_TEMPFILENAME] 
b990: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
b9a0: 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67  to have SQLite g
b9b0: 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d  enerate a.** tem
b9c0: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20  porary filename 
b9d0: 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
b9e0: 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73  lgorithm that is
b9f0: 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e   followed to gen
ba00: 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  erate.** tempora
ba10: 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72  ry filenames for
ba20: 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64   TEMP tables and
ba30: 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20   other internal 
ba40: 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72  uses.  The.** ar
ba50: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
ba60: 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20   a char** which 
ba70: 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77  will be filled w
ba80: 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ith the filename
ba90: 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  .** written into
baa0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
bab0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
bac0: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63  alloc()].  The c
bad0: 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20  aller should.** 
bae0: 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
baf0: 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72  free()] on the r
bb00: 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61  esult to avoid a
bb10: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a   memory leak..**
bb20: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bb30: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
bb40: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
bb50: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
bb60: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
bb70: 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79  is used to query
bb80: 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d   or set the.** m
bb90: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
bba0: 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c   bytes that will
bbb0: 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d   be used for mem
bbc0: 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a  ory-mapped I/O..
bbd0: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
bbe0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
bbf0: 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20  a value of type 
bc00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68  sqlite3_int64 th
bc10: 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69  at.** is an advi
bc20: 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  sory maximum num
bc30: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
bc40: 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f  the file to memo
bc50: 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20  ry map.  The.** 
bc60: 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77  pointer is overw
bc70: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
bc80: 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20  old value.  The 
bc90: 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61  limit is not cha
bca0: 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76  nged if.** the v
bcb0: 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20  alue originally 
bcc0: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65  pointed to is ne
bcd0: 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74  gative, and so t
bce0: 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74  he current limit
bcf0: 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72   .** can be quer
bd00: 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69  ied by passing i
bd10: 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  n a pointer to a
bd20: 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
bd30: 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d  .  This.** file-
bd40: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
bd50: 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d  internally to im
bd60: 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20  plement [PRAGMA 
bd70: 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a  mmap_size]..**.*
bd80: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bd90: 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20  CNTL_TRACE]].** 
bda0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bdb0: 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f  L_TRACE] file co
bdc0: 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61  ntrol provides a
bdd0: 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74  dvisory informat
bde0: 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46  ion.** to the VF
bdf0: 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65  S about what the
be00: 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f   higher layers o
be10: 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61  f the SQLite sta
be20: 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a  ck are doing..**
be30: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   This file contr
be40: 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f  ol is used by so
be50: 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20  me VFS activity 
be60: 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e  tracing [shims].
be70: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
be80: 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   is a zero-termi
be90: 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48  nated string.  H
bea0: 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20  igher layers in 
beb0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74  the.** SQLite st
bec0: 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65  ack may generate
bed0: 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68   instances of th
bee0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
bef0: 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  if.** the [SQLIT
bf00: 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43  E_USE_FCNTL_TRAC
bf10: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
bf20: 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
bf30: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
bf40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
bf50: 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b  MOVED]].** The [
bf60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
bf70: 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e  _MOVED] file con
bf80: 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20  trol interprets 
bf90: 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20  its argument as 
bfa0: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
bfb0: 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69  an integer and i
bfc0: 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65  t writes a boole
bfd0: 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  an into that int
bfe0: 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a  eger depending.*
bff0: 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20  * on whether or 
c000: 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73  not the file has
c010: 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d   been renamed, m
c020: 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64  oved, or deleted
c030: 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73   since it.** was
c040: 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a   first opened..*
c050: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c060: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45  E_FCNTL_WIN32_GE
c070: 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68  T_HANDLE]].** Th
c080: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c090: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45  WIN32_GET_HANDLE
c0a0: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
c0b0: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
c0c0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
c0d0: 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e   native file han
c0e0: 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  dle associated w
c0f0: 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c  ith a file handl
c100: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a  e.  This file.**
c110: 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72   control interpr
c120: 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74  ets its argument
c130: 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   as a pointer to
c140: 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68   a native file h
c150: 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69  andle and.** wri
c160: 74 65 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e  tes the resultin
c170: 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a  g value there..*
c180: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c190: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
c1a0: 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68  T_HANDLE]].** Th
c1b0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c1c0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
c1d0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
c1e0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
c1f0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
c200: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
c210: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
c220: 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20  o swap the file 
c230: 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20  handle with the 
c240: 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  one.** pointed t
c250: 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72  o by the pArg ar
c260: 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61  gument.  This ca
c270: 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64  pability is used
c280: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a   during testing.
c290: 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ** and only need
c2a0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
c2b0: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
c2c0: 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ST is defined..*
c2d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c2e0: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
c2f0: 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  K]].** The [SQLI
c300: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
c310: 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20  CK] is a signal 
c320: 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72  to the VFS layer
c330: 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a   that it might.*
c340: 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75  * be advantageou
c350: 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68  s to block on th
c360: 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20  e next WAL lock 
c370: 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e  if the lock is n
c380: 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ot immediately.*
c390: 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68  * available.  Th
c3a0: 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20  e WAL subsystem 
c3b0: 69 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e  issues this sign
c3c0: 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a  al during rare.*
c3d0: 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  * circumstances 
c3e0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20  in order to fix 
c3f0: 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70  a problem with p
c400: 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f  riority inversio
c410: 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  n..** Applicatio
c420: 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f  ns should <em>no
c430: 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20  t</em> use this 
c440: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a  file-control..**
c450: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c460: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a  _FCNTL_ZIPVFS]].
c470: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
c480: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63  CNTL_ZIPVFS] opc
c490: 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ode is implement
c4a0: 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c  ed by zipvfs onl
c4b0: 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  y. All other.** 
c4c0: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
c4d0: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
c4e0: 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  D for this opcod
c4f0: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
c500: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
c510: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
c520: 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f  _FCNTL_RBU] opco
c530: 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  de is implemente
c540: 64 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c  d by the special
c550: 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20   VFS used by.** 
c560: 74 68 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f  the RBU extensio
c570: 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68  n only.  All oth
c580: 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65  er VFS should re
c590: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
c5a0: 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73  OUND for.** this
c5b0: 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a   opcode.  .**.**
c5c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c5d0: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
c5e0: 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74  _WRITE]].** If t
c5f0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c600: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
c610: 49 54 45 5d 20 6f 70 63 6f 64 65 20 72 65 74 75  ITE] opcode retu
c620: 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74  rns SQLITE_OK, t
c630: 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20  hen.** the file 
c640: 64 65 73 63 72 69 70 74 6f 72 20 69 73 20 70 6c  descriptor is pl
c650: 61 63 65 64 20 69 6e 20 22 62 61 74 63 68 20 77  aced in "batch w
c660: 72 69 74 65 20 6d 6f 64 65 22 2c 20 77 68 69 63  rite mode", whic
c670: 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73  h.** means all s
c680: 75 62 73 65 71 75 65 6e 74 20 77 72 69 74 65 20  ubsequent write 
c690: 6f 70 65 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20  operations will 
c6a0: 62 65 20 64 65 66 65 72 72 65 64 20 61 6e 64 20  be deferred and 
c6b0: 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c  done.** atomical
c6c0: 6c 79 20 61 74 20 74 68 65 20 6e 65 78 74 20 5b  ly at the next [
c6d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
c6e0: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
c6f0: 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74  ].  Systems.** t
c700: 68 61 74 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f  hat do not suppo
c710: 72 74 20 62 61 74 63 68 20 61 74 6f 6d 69 63 20  rt batch atomic 
c720: 77 72 69 74 65 73 20 77 69 6c 6c 20 72 65 74 75  writes will retu
c730: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
c740: 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e  ND..** ^Followin
c750: 67 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 53  g a successful S
c760: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
c770: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 61  N_ATOMIC_WRITE a
c780: 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74  nd prior to.** t
c790: 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49  he closing [SQLI
c7a0: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c7b0: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72  ATOMIC_WRITE] or
c7c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
c7d0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
c7e0: 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c 69 74 65  C_WRITE], SQLite
c7f0: 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f   will make.** no
c800: 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 63   VFS interface c
c810: 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  alls on the same
c820: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
c830: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 0a  file descriptor.
c840: 2a 2a 20 65 78 63 65 70 74 20 66 6f 72 20 63 61  ** except for ca
c850: 6c 6c 73 20 74 6f 20 74 68 65 20 78 57 72 69 74  lls to the xWrit
c860: 65 20 6d 65 74 68 6f 64 20 61 6e 64 20 74 68 65  e method and the
c870: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
c880: 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51  thod.** with [SQ
c890: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
c8a0: 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  HINT]..**.** <li
c8b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c8c0: 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52  COMMIT_ATOMIC_WR
c8d0: 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ITE]].** The [SQ
c8e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
c8f0: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  T_ATOMIC_WRITE] 
c900: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c  opcode causes al
c910: 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61  l write.** opera
c920: 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20  tions since the 
c930: 70 72 65 76 69 6f 75 73 20 73 75 63 63 65 73 73  previous success
c940: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20  ful call to .** 
c950: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45  [SQLITE_FCNTL_BE
c960: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
c970: 5d 20 74 6f 20 62 65 20 70 65 72 66 6f 72 6d 65  ] to be performe
c980: 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a  d atomically..**
c990: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   This file contr
c9a0: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
c9b0: 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e  TE_OK] if and on
c9c0: 6c 79 20 69 66 20 74 68 65 20 77 72 69 74 65 73  ly if the writes
c9d0: 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72   were.** all per
c9e0: 66 6f 72 6d 65 64 20 73 75 63 63 65 73 73 66 75  formed successfu
c9f0: 6c 6c 79 20 61 6e 64 20 68 61 76 65 20 62 65 65  lly and have bee
ca00: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70  n committed to p
ca10: 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72 61 67  ersistent storag
ca20: 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  e..** ^Regardles
ca30: 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
ca40: 6e 6f 74 20 69 74 20 69 73 20 73 75 63 63 65 73  not it is succes
ca50: 73 66 75 6c 2c 20 74 68 69 73 20 66 69 6c 65 20  sful, this file 
ca60: 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a  control takes.**
ca70: 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69   the file descri
ca80: 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63  ptor out of batc
ca90: 68 20 77 72 69 74 65 20 6d 6f 64 65 20 73 6f 20  h write mode so 
caa0: 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75  that all subsequ
cab0: 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65  ent.** write ope
cac0: 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65  rations are inde
cad0: 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c  pendent..** ^SQL
cae0: 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
caf0: 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e  nvoke SQLITE_FCN
cb00: 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  TL_COMMIT_ATOMIC
cb10: 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a  _WRITE without.*
cb20: 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  * a prior succes
cb30: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51  sful call to [SQ
cb40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
cb50: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a  _ATOMIC_WRITE]..
cb60: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
cb70: 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43  TE_FCNTL_ROLLBAC
cb80: 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d  K_ATOMIC_WRITE]]
cb90: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
cba0: 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41  FCNTL_ROLLBACK_A
cbb0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63  TOMIC_WRITE] opc
cbc0: 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77  ode causes all w
cbd0: 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  rite.** operatio
cbe0: 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72 65  ns since the pre
cbf0: 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c  vious successful
cc00: 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51   call to .** [SQ
cc10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
cc20: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74  _ATOMIC_WRITE] t
cc30: 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  o be rolled back
cc40: 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65 20  ..** ^This file 
cc50: 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 20 74 68  control takes th
cc60: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
cc70: 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77  r out of batch w
cc80: 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20  rite mode.** so 
cc90: 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75  that all subsequ
cca0: 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61 74  ent write operat
ccb0: 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e  ions are indepen
ccc0: 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  dent..** ^SQLite
ccd0: 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
cce0: 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ke SQLITE_FCNTL_
ccf0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
cd00: 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a  WRITE without.**
cd10: 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73   a prior success
cd20: 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c  ful call to [SQL
cd30: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
cd40: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a  ATOMIC_WRITE]..*
cd50: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </ul>.*/.#defi
cd60: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cd70: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
cd80: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
cd90: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47  e SQLITE_FCNTL_G
cda0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
cdb0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
cdc0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
cdd0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
cde0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
cdf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
ce00: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
ce10: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
ce20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
ce30: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  _HINT           
ce40: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
ce50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
ce60: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
ce70: 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
ce80: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
ce90: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
cea0: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
ceb0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
cec0: 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20  ITTED           
ced0: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
cee0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
cef0: 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20  _RETRY          
cf00: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
cf10: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
cf20: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30  AL            10
cf30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cf40: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20  FCNTL_OVERWRITE 
cf50: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a               11.
cf60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cf70: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20  CNTL_VFSNAME    
cf80: 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23              12.#
cf90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cfa0: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
cfb0: 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64  ERWRITE    13.#d
cfc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cfd0: 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TL_PRAGMA       
cfe0: 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65            14.#de
cff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d000: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20  L_BUSYHANDLER   
d010: 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66           15.#def
d020: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d030: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20  _TEMPFILENAME   
d040: 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69          16.#defi
d050: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d060: 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20  MMAP_SIZE       
d070: 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e         18.#defin
d080: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
d090: 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20  RACE            
d0a0: 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65        19.#define
d0b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41   SQLITE_FCNTL_HA
d0c0: 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20  S_MOVED         
d0d0: 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20       20.#define 
d0e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
d0f0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
d100: 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53      21.#define S
d110: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
d120: 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20  IT_PHASETWO     
d130: 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51     22.#define SQ
d140: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
d150: 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _SET_HANDLE     
d160: 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    23.#define SQL
d170: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
d180: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  OCK             
d190: 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   24.#define SQLI
d1a0: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20  TE_FCNTL_ZIPVFS 
d1b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d1c0: 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  25.#define SQLIT
d1d0: 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20  E_FCNTL_RBU     
d1e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
d1f0: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
d200: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
d210: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37  ER            27
d220: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d230: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
d240: 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a  INTER        28.
d250: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d260: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
d270: 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23  ANDLE       29.#
d280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d290: 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20  NTL_PDB         
d2a0: 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 23 64             30.#d
d2b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d2c0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
d2d0: 57 52 49 54 45 20 20 20 20 20 33 31 0a 23 64 65  WRITE     31.#de
d2e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d2f0: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
d300: 57 52 49 54 45 20 20 20 20 33 32 0a 23 64 65 66  WRITE    32.#def
d310: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d320: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
d330: 5f 57 52 49 54 45 20 20 33 33 0a 0a 2f 2a 20 64  _WRITE  33../* d
d340: 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20  eprecated names 
d350: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
d360: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
d370: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
d380: 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52  FCNTL_GET_LOCKPR
d390: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
d3a0: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
d3b0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
d3c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c  LITE_FCNTL_SET_L
d3d0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
d3e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
d3f0: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
d400: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
d410: 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a  LAST_ERRNO.../*.
d420: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
d430: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
d440: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
d450: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
d460: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
d470: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
d480: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
d490: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
d4a0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
d4b0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
d4c0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
d4d0: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
d4e0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
d4f0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
d500: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
d510: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
d520: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
d530: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
d540: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
d550: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
d560: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
d570: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
d580: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
d590: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
d5a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
d5b0: 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65  F: Loadable Exte
d5c0: 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a  nsion Thunk.**.*
d5d0: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * A pointer to t
d5e0: 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65  he opaque sqlite
d5f0: 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73  3_api_routines s
d600: 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73 73  tructure is pass
d610: 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69  ed as.** the thi
d620: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
d630: 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20  entry points of 
d640: 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73  [loadable extens
d650: 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20  ions].  This.** 
d660: 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 62  structure must b
d670: 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f  e typedefed in o
d680: 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f  rder to work aro
d690: 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72  und compiler war
d6a0: 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65  nings.** on some
d6b0: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74   platforms..*/.t
d6c0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
d6d0: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
d6e0: 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  es sqlite3_api_r
d6f0: 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20  outines;../*.** 
d700: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
d710: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
d720: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
d730: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
d740: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
d750: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
d760: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
d770: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
d780: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
d790: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
d7a0: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
d7b0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
d7c0: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
d7d0: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
d7e0: 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a   system".  See.*
d7f0: 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53  * the [VFS | VFS
d800: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
d810: 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f  for further info
d820: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
d830: 68 65 20 56 46 53 20 69 6e 74 65 72 66 61 63 65  he VFS interface
d840: 20 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 78   is sometimes ex
d850: 74 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e 67  tended by adding
d860: 20 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74   new methods ont
d870: 6f 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 45  o.** the end.  E
d880: 61 63 68 20 74 69 6d 65 20 73 75 63 68 20 61 6e  ach time such an
d890: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72   extension occur
d8a0: 73 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  s, the iVersion 
d8b0: 66 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72  field.** is incr
d8c0: 65 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69 56  emented.  The iV
d8d0: 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 61  ersion value sta
d8e0: 72 74 65 64 20 6f 75 74 20 61 73 20 31 20 69 6e  rted out as 1 in
d8f0: 0a 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73  .** SQLite [vers
d900: 69 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64  ion 3.5.0] on [d
d910: 61 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68  ateof:3.5.0], th
d920: 65 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f 20  en increased to 
d930: 32 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 65  2.** with SQLite
d940: 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d   [version 3.7.0]
d950: 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e   on [dateof:3.7.
d960: 30 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e 63  0], and then inc
d970: 72 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77  reased.** to 3 w
d980: 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73  ith SQLite [vers
d990: 69 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64  ion 3.7.6] on [d
d9a0: 61 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41  ateof:3.7.6].  A
d9b0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
d9c0: 0a 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65 6e  .** may be appen
d9d0: 64 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ded to the sqlit
d9e0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 6e  e3_vfs object an
d9f0: 64 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  d the iVersion v
da00: 61 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72  alue.** may incr
da10: 65 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66 75  ease again in fu
da20: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
da30: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65   SQLite..** Note
da40: 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74   that the struct
da50: 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  ure.** of the sq
da60: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
da70: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
da80: 74 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a  transition from.
da90: 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69  ** SQLite [versi
daa0: 6f 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65  on 3.5.9] to [ve
dab0: 72 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20  rsion 3.6.0] on 
dac0: 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a  [dateof:3.6.0].*
dad0: 2a 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  * and yet the iV
dae0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
daf0: 20 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a   not modified..*
db00: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
db10: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
db20: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
db30: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
db40: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
db50: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
db60: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
db70: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
db80: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
db90: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
dba0: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
dbb0: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
dbc0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
dbd0: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
dbe0: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
dbf0: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
dc00: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
dc10: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
dc20: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
dc30: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
dc40: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
dc50: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
dc60: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
dc70: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
dc80: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
dc90: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
dca0: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
dcb0: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
dcc0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
dcd0: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
dce0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
dcf0: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
dd00: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
dd10: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
dd20: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
dd30: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
dd40: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
dd50: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
dd60: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
dd70: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
dd80: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
dd90: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
dda0: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
ddb0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
ddc0: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
ddd0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
dde0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
ddf0: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
de00: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
de10: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
de20: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
de30: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
de40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
de50: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
de60: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
de70: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
de80: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
de90: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
dea0: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
deb0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
dec0: 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51  s.xOpen]].** ^SQ
ded0: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
dee0: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
def0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
df00: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
df10: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
df20: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
df30: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
df40: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
df50: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
df60: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
df70: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
df80: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
df90: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
dfa0: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
dfb0: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
dfc0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
dfd0: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
dfe0: 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70  e than.** 11 alp
dff0: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
e000: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
e010: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
e020: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
e030: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
e040: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
e050: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
e060: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
e070: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
e080: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
e090: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
e0a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
e0b0: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
e0c0: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
e0d0: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
e0e0: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
e0f0: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
e100: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
e110: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
e120: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
e130: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
e140: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
e150: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
e160: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
e170: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
e180: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
e190: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
e1a0: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
e1b0: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
e1c0: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
e1d0: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
e1e0: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
e1f0: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
e200: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
e210: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
e220: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
e230: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
e240: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
e250: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
e260: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
e270: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
e280: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
e290: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
e2a0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
e2b0: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
e2c0: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
e2d0: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
e2e0: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
e2f0: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
e300: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
e310: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
e320: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
e330: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
e340: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
e350: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
e360: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
e370: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
e380: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
e390: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
e3a0: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
e3b0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
e3c0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
e3d0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
e3e0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
e3f0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
e400: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
e410: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
e420: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e430: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
e440: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e450: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
e460: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e470: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
e480: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
e490: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
e4a0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
e4b0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
e4c0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
e4d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
e4e0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
e4f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
e500: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
e510: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
e520: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
e530: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
e540: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
e550: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
e560: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
e570: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
e580: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
e590: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
e5a0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
e5b0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
e5c0: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
e5d0: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
e5e0: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
e5f0: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
e600: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
e610: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
e620: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
e630: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
e640: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
e650: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
e660: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
e670: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
e680: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
e690: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
e6a0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
e6b0: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
e6c0: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
e6d0: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
e6e0: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
e6f0: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
e700: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
e710: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
e720: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
e730: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
e740: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
e750: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
e760: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
e770: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
e780: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
e790: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
e7a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
e7b0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
e7c0: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
e7d0: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
e7e0: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
e7f0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
e800: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
e810: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
e820: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
e830: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
e840: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
e850: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
e860: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
e870: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
e880: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
e890: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
e8a0: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
e8b0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
e8c0: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
e8d0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
e8e0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
e8f0: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
e900: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
e910: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
e920: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
e930: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
e940: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
e950: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
e960: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
e970: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
e980: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
e990: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
e9a0: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
e9b0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
e9c0: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
e9d0: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
e9e0: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
e9f0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
ea00: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
ea10: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
ea20: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
ea30: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
ea40: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
ea50: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
ea60: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
ea70: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
ea80: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
ea90: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
eaa0: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
eab0: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
eac0: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
ead0: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
eae0: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
eaf0: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
eb00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
eb10: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
eb20: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
eb30: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
eb40: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
eb50: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
eb60: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
eb70: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
eb80: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
eb90: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
eba0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
ebb0: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
ebc0: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
ebd0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
ebe0: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
ebf0: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
ec00: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
ec10: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
ec20: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
ec30: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
ec40: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
ec50: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
ec60: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
ec70: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
ec80: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
ec90: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
eca0: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
ecb0: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
ecc0: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
ecd0: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
ece0: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
ecf0: 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a  vfs.xAccess]].**
ed00: 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75   ^The flags argu
ed10: 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28  ment to xAccess(
ed20: 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45  ) may be [SQLITE
ed30: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a  _ACCESS_EXISTS].
ed40: 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74  ** to test for t
ed50: 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20  he existence of 
ed60: 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  a file, or [SQLI
ed70: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
ed80: 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20  ITE] to.** test 
ed90: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
eda0: 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  s readable and w
edb0: 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c  ritable, or [SQL
edc0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d  ITE_ACCESS_READ]
edd0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74  .** to test whet
ede0: 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74  her a file is at
edf0: 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e   least readable.
ee00: 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20     The file can 
ee10: 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72  be a.** director
ee20: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  y..**.** ^SQLite
ee30: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
ee40: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
ee50: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
ee60: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
ee70: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
ee80: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
ee90: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
eea0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
eeb0: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
eec0: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
eed0: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
eee0: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
eef0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
ef00: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
ef10: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
ef20: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
ef30: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
ef40: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
ef50: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
ef60: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
ef70: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
ef80: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
ef90: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
efa0: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
efb0: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
efc0: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
efd0: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
efe0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
eff0: 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e  Sleep(), xCurren
f000: 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75  tTime(), and xCu
f010: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
f020: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
f030: 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  re not strictly 
f040: 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69  a part of the fi
f050: 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68  lesystem, but th
f060: 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64  ey are.** includ
f070: 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  ed in the VFS st
f080: 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70  ructure for comp
f090: 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65  leteness..** The
f0a0: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66   xRandomness() f
f0b0: 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73  unction attempts
f0c0: 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65   to return nByte
f0d0: 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f  s bytes.** of go
f0e0: 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f  od-quality rando
f0f0: 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e  mness into zOut.
f100: 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c    The return val
f110: 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74  ue is.** the act
f120: 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  ual number of by
f130: 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
f140: 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54  s obtained..** T
f150: 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
f160: 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61  od causes the ca
f170: 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20  lling thread to 
f180: 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20  sleep for at.** 
f190: 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72  least the number
f1a0: 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73   of microseconds
f1b0: 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43   given.  ^The xC
f1c0: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
f1d0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
f1e0: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
f1f0: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
f200: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
f210: 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e   as.** a floatin
f220: 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a  g point value..*
f230: 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54  * ^The xCurrentT
f240: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
f250: 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e  d returns, as an
f260: 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75   integer, the Ju
f270: 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62  lian.** Day Numb
f280: 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79  er multiplied by
f290: 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e   86400000 (the n
f2a0: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
f2b0: 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32  conds in .** a 2
f2c0: 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a  4-hour day).  .*
f2d0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
f2e0: 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54  se the xCurrentT
f2f0: 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f  imeInt64() metho
f300: 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72  d to get the cur
f310: 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64  rent.** date and
f320: 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65   time if that me
f330: 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c  thod is availabl
f340: 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69  e (if iVersion i
f350: 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74  s 2 or .** great
f360: 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74  er and the funct
f370: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
f380: 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c  ot NULL) and wil
f390: 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74  l fall back.** t
f3a0: 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  o xCurrentTime()
f3b0: 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65   if xCurrentTime
f3c0: 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61  Int64() is unava
f3d0: 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ilable..**.** ^T
f3e0: 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c  he xSetSystemCal
f3f0: 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43  l(), xGetSystemC
f400: 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74  all(), and xNest
f410: 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74  SystemCall() int
f420: 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e  erfaces.** are n
f430: 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53  ot used by the S
f440: 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65  QLite core.  The
f450: 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65  se optional inte
f460: 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69  rfaces are provi
f470: 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56  ded.** by some V
f480: 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61  FSes to facilita
f490: 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68  te testing of th
f4a0: 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f  e VFS code. By o
f4b0: 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79  verriding .** sy
f4c0: 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20  stem calls with 
f4d0: 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20  functions under 
f4e0: 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74  its control, a t
f4f0: 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a  est program can.
f500: 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c  ** simulate faul
f510: 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e  ts and error con
f520: 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75  ditions that wou
f530: 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20  ld otherwise be 
f540: 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20  difficult.** or 
f550: 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  impossible to in
f560: 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f  duce.  The set o
f570: 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74  f system calls t
f580: 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72  hat can be overr
f590: 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20  idden.** varies 
f5a0: 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20  from one VFS to 
f5b0: 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f  another, and fro
f5c0: 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66  m one version of
f5d0: 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f   the same VFS to
f5e0: 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41   the.** next.  A
f5f0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
f600: 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72   use these inter
f610: 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72  faces must be pr
f620: 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a  epared for any.*
f630: 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73  * or all of thes
f640: 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20  e interfaces to 
f650: 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74  be NULL or for t
f660: 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f  heir behavior to
f670: 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20   change.** from 
f680: 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  one release to t
f690: 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  he next.  Applic
f6a0: 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20  ations must not 
f6b0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73  attempt to acces
f6c0: 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73  s.** any of thes
f6d0: 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65  e methods if the
f6e0: 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65   iVersion of the
f6f0: 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61   VFS is less tha
f700: 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n 3..*/.typedef 
f710: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
f720: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
f730: 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73  typedef void (*s
f740: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
f750: 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63  tr)(void);.struc
f760: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a  t sqlite3_vfs {.
f770: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20    int iVersion; 
f780: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74             /* St
f790: 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20  ructure version 
f7a0: 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c  number (currentl
f7b0: 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a  y 3) */.  int sz
f7c0: 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20  OsFile;         
f7d0: 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75     /* Size of su
f7e0: 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33  bclassed sqlite3
f7f0: 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d  _file */.  int m
f800: 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20  xPathname;      
f810: 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66      /* Maximum f
f820: 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e  ile pathname len
f830: 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  gth */.  sqlite3
f840: 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20  _vfs *pNext;    
f850: 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74    /* Next regist
f860: 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f  ered VFS */.  co
f870: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b  nst char *zName;
f880: 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
f890: 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66  f this virtual f
f8a0: 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20  ile system */.  
f8b0: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
f8c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e           /* Poin
f8d0: 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69  ter to applicati
f8e0: 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61  on-specific data
f8f0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65   */.  int (*xOpe
f900: 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  n)(sqlite3_vfs*,
f910: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
f920: 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  me, sqlite3_file
f930: 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
f940: 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74    int flags, int
f950: 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20   *pOutFlags);.  
f960: 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73  int (*xDelete)(s
f970: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
f980: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
f990: 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20  int syncDir);.  
f9a0: 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73  int (*xAccess)(s
f9b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
f9c0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
f9d0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
f9e0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20  pResOut);.  int 
f9f0: 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29  (*xFullPathname)
fa00: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
fa10: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
fa20: 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72  , int nOut, char
fa30: 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20   *zOut);.  void 
fa40: 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69  *(*xDlOpen)(sqli
fa50: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
fa60: 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29  char *zFilename)
fa70: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72  ;.  void (*xDlEr
fa80: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
fa90: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
faa0: 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20  ar *zErrMsg);.  
fab0: 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29  void (*(*xDlSym)
fac0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f  (sqlite3_vfs*,vo
fad0: 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  id*, const char 
fae0: 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29  *zSymbol))(void)
faf0: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c  ;.  void (*xDlCl
fb00: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ose)(sqlite3_vfs
fb10: 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74  *, void*);.  int
fb20: 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28   (*xRandomness)(
fb30: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
fb40: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
fb50: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Out);.  int (*xS
fb60: 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66  leep)(sqlite3_vf
fb70: 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63  s*, int microsec
fb80: 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  onds);.  int (*x
fb90: 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c  CurrentTime)(sql
fba0: 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c  ite3_vfs*, doubl
fbb0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65  e*);.  int (*xGe
fbc0: 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69  tLastError)(sqli
fbd0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63  te3_vfs*, int, c
fbe0: 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a  har *);.  /*.  *
fbf0: 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
fc00: 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
fc10: 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
fc20: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20  te_vfs object.  
fc30: 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  ** definition.  
fc40: 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f  Those that follo
fc50: 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76  w are added in v
fc60: 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65  ersion 2 or late
fc70: 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  r.  */.  int (*x
fc80: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
fc90: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
fca0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b  sqlite3_int64*);
fcb0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
fcc0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
fcd0: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61   in versions 1 a
fce0: 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69  nd 2 of the sqli
fcf0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
fd00: 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20   ** Those below 
fd10: 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  are for version 
fd20: 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20  3 and greater.. 
fd30: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74   */.  int (*xSet
fd40: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
fd50: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
fd60: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
fd70: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
fd80: 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73  );.  sqlite3_sys
fd90: 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53  call_ptr (*xGetS
fda0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
fdb0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
fdc0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63  har *zName);.  c
fdd0: 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65  onst char *(*xNe
fde0: 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  xtSystemCall)(sq
fdf0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
fe00: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
fe10: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
fe20: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
fe30: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68  in versions 1 th
fe40: 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73  rough 3 of the s
fe50: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
fe60: 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64  ..  ** New field
fe70: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
fe80: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
fe90: 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73  ions.  The iVers
fea0: 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77  ion.  ** value w
feb0: 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68  ill increment wh
fec0: 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70  enever this happ
fed0: 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f  ens. .  */.};../
fee0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
fef0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
ff00: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
ff10: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
ff20: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
ff30: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
ff40: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
ff50: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
ff60: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
ff70: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
ff80: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
ff90: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
ffa0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
ffb0: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
ffc0: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
ffd0: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
ffe0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
fff0: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
10000 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
10010 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
10020 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
10030 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
10040 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
10050 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10060 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
10070 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20  ether the named 
10080 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74  directory is bot
10090 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77  h readable and w
100a0 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f  ritable.** (in o
100b0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66  ther words, if f
100c0 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65  iles can be adde
100d0 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20  d, removed, and 
100e0 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a  renamed within.*
100f0 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29  * the directory)
10100 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
10110 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
10120 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72   constant is cur
10130 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79  rently used only
10140 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70   by the.** [temp
10150 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
10160 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68   pragma], though
10170 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e   this could chan
10180 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
10190 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
101a0 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  ite..** With SQL
101b0 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c  ITE_ACCESS_READ,
101c0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
101d0 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
101e0 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
101f0 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65  s readable.  The
10200 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10210 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a  EAD constant is.
10220 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75  ** currently unu
10230 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d  sed, though it m
10240 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20  ight be used in 
10250 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  a future release
10260 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a   of.** SQLite..*
10270 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10280 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20  _ACCESS_EXISTS  
10290 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
102a0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
102b0 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20  ITE 1   /* Used 
102c0 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73  by PRAGMA temp_s
102d0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a  tore_directory *
102e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
102f0 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
10300 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20    2   /* Unused 
10310 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
10320 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
10330 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
10340 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
10350 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
10360 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76  nts define the v
10370 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f  arious locking o
10380 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c  perations.** all
10390 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d  owed by the xShm
103a0 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b  Lock method of [
103b0 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
103c0 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c  ds].  The.** fol
103d0 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f  lowing are the o
103e0 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e  nly legal combin
103f0 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20  ations of flags 
10400 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f  to the.** xShmLo
10410 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  ck method:.**.**
10420 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53   <ul>.** <li>  S
10430 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
10440 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
10450 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
10460 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
10470 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
10480 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  VE.** <li>  SQLI
10490 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
104a0 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
104b0 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
104c0 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
104d0 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
104e0 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IVE.** </ul>.**.
104f0 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e  ** When unlockin
10500 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52  g, the same SHAR
10510 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  ED or EXCLUSIVE 
10520 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70  flag must be sup
10530 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20  plied as.** was 
10540 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72  given on the cor
10550 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e  responding lock.
10560 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68    .**.** The xSh
10570 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e  mLock method can
10580 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
10590 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
105a0 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65   SHARED or.** be
105b0 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
105c0 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49  nd EXCLUSIVE.  I
105d0 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74  t cannot transit
105e0 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52  ion between SHAR
105f0 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53  ED.** and EXCLUS
10600 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  IVE..*/.#define 
10610 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
10620 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e  K       1.#defin
10630 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43  e SQLITE_SHM_LOC
10640 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  K         2.#def
10650 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  ine SQLITE_SHM_S
10660 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64  HARED       4.#d
10670 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
10680 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a  _EXCLUSIVE    8.
10690 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
106a0 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63   Maximum xShmLoc
106b0 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68  k index.**.** Th
106c0 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
106d0 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d on [sqlite3_io
106e0 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73  _methods] may us
106f0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  e values.** betw
10700 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75  een 0 and this u
10710 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74  pper bound as it
10720 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d  s "offset" argum
10730 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ent..** The SQLi
10740 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76  te core will nev
10750 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  er attempt to ac
10760 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65  quire or release
10770 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69   a.** lock outsi
10780 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65  de of this range
10790 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
107a0 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20  TE_SHM_NLOCK    
107b0 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41      8.../*.** CA
107c0 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69  PI3REF: Initiali
107d0 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ze The SQLite Li
107e0 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  brary.**.** ^The
107f0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10800 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e  ize() routine in
10810 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a  itializes the.**
10820 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
10830 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
10840 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e  hutdown() routin
10850 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73  e.** deallocates
10860 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74   any resources t
10870 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74  hat were allocat
10880 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
10890 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54  itialize()..** T
108a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
108b0 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69  e designed to ai
108c0 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69  d in process ini
108d0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a  tialization and.
108e0 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65  ** shutdown on e
108f0 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e  mbedded systems.
10900 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70    Workstation ap
10910 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67  plications using
10920 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61  .** SQLite norma
10930 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  lly do not need 
10940 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  to invoke either
10950 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
10960 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  es..**.** A call
10970 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
10980 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22  ialize() is an "
10990 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
109a0 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20  if it is.** the 
109b0 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
109c0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
109d0 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e  is invoked durin
109e0 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f  g the lifetime o
109f0 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73  f.** the process
10a00 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68  , or if it is th
10a10 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
10a20 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10a30 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
10a40 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c  following a call
10a50 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
10a60 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20  down().  ^(Only 
10a70 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
10a80 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  l.** of sqlite3_
10a90 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65  initialize() doe
10aa0 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61  s any initializa
10ab0 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72  tion.  All other
10ac0 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61   calls.** are ha
10ad0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
10ae0 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
10af0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10b00 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  n() is an "effec
10b10 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
10b20 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
10b30 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
10b40 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63  _shutdown() sinc
10b50 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  e the last sqlit
10b60 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
10b70 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65    ^(Only.** an e
10b80 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f  ffective call to
10b90 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10ba0 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69  n() does any dei
10bb0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  nitialization..*
10bc0 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69  * All other vali
10bd0 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  d calls to sqlit
10be0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72  e3_shutdown() ar
10bf0 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
10c00 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  s.)^.**.** The s
10c10 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10c20 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
10c30 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74   threadsafe, but
10c40 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
10c50 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20  n().** is not.  
10c60 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
10c70 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65  down() interface
10c80 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61   must only be ca
10c90 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73  lled from a.** s
10ca0 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41  ingle thread.  A
10cb0 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73  ll open [databas
10cc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d  e connections] m
10cd0 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e  ust be closed an
10ce0 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53  d all.** other S
10cf0 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20  QLite resources 
10d00 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61  must be dealloca
10d10 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76  ted prior to inv
10d20 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  oking.** sqlite3
10d30 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a  _shutdown()..**.
10d40 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74  ** Among other t
10d50 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f  hings, ^sqlite3_
10d60 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c  initialize() wil
10d70 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  l invoke.** sqli
10d80 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
10d90 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69  Similarly, ^sqli
10da0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
10db0 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71  * will invoke sq
10dc0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a  lite3_os_end()..
10dd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
10de0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10df0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
10e00 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
10e10 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66  uccess..** ^If f
10e20 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20  or some reason, 
10e30 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10e40 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  ze() is unable t
10e50 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20  o initialize.** 
10e60 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72  the library (per
10e70 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c  haps it is unabl
10e80 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20  e to allocate a 
10e90 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20  needed resource 
10ea0 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74  such.** as a mut
10eb0 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61  ex) it returns a
10ec0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  n [error code] o
10ed0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
10ee0 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  E_OK]..**.** ^Th
10ef0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10f00 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
10f10 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61  s called interna
10f20 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65  lly by many othe
10f30 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
10f40 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61  rfaces so that a
10f50 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
10f60 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e  ually does not n
10f70 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65  eed to.** invoke
10f80 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10f90 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ize() directly. 
10fa0 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73   For example, [s
10fb0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
10fc0 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f  * calls sqlite3_
10fd0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20  initialize() so 
10fe0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
10ff0 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ry will be autom
11000 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74  atically.** init
11010 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71  ialized when [sq
11020 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73  lite3_open()] is
11030 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61   called if it ha
11040 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c  s not be initial
11050 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e  ized.** already.
11060 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53    ^However, if S
11070 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11080 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  d with the [SQLI
11090 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
110a0 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
110b0 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74  e option, then t
110c0 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c  he automatic cal
110d0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ls to sqlite3_in
110e0 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72  itialize().** ar
110f0 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68  e omitted and th
11100 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
11110 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  st call sqlite3_
11120 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
11130 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74  ectly.** prior t
11140 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
11150 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
11160 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d  ce.  For maximum
11170 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a   portability,.**
11180 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
11190 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
111a0 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f  ions always invo
111b0 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
111c0 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63  alize().** direc
111d0 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69  tly prior to usi
111e0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
111f0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
11200 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a  Future releases.
11210 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ** of SQLite may
11220 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20   require this.  
11230 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11240 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68  the behavior exh
11250 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53  ibited.** when S
11260 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11270 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f  d with [SQLITE_O
11280 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69  MIT_AUTOINIT] mi
11290 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a  ght become the.*
112a0 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  * default behavi
112b0 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  or in some futur
112c0 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
112d0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite..**.** The s
112e0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
112f0 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70   routine does op
11300 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
11310 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69  pecific.** initi
11320 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65  alization of the
11330 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e   SQLite library.
11340 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
11350 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  _end().** routin
11360 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  e undoes the eff
11370 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ect of sqlite3_o
11380 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63  s_init().  Typic
11390 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66  al tasks.** perf
113a0 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72  ormed by these r
113b0 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20  outines include 
113c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65  allocation or de
113d0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
113e0 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65   static resource
113f0 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  s, initializatio
11400 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69  n of global vari
11410 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e  ables,.** settin
11420 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b  g up a default [
11430 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64  sqlite3_vfs] mod
11440 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20  ule, or setting 
11450 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20  up.** a default 
11460 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73  configuration us
11470 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  ing [sqlite3_con
11480 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  fig()]..**.** Th
11490 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
114a0 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b  ould never invok
114b0 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  e either sqlite3
114c0 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72  _os_init().** or
114d0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
114e0 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65  ) directly.  The
114f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
11500 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a  uld only invoke.
11510 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ** sqlite3_initi
11520 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69  alize() and sqli
11530 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
11540 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
11550 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66  init().** interf
11560 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75  ace is called au
11570 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
11580 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11590 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  e() and.** sqlit
115a0 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63  e3_os_end() is c
115b0 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33  alled by sqlite3
115c0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70  _shutdown().  Ap
115d0 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70  propriate.** imp
115e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
115f0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
11600 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
11610 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62  s_end().** are b
11620 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
11630 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70   when it is comp
11640 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57  iled for Unix, W
11650 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e  indows, or OS/2.
11660 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d  .** When [custom
11670 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20   builds | built 
11680 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f  for other platfo
11690 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74  rms].** (using t
116a0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54  he [SQLITE_OS_OT
116b0 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74  HER=1] compile-t
116c0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74  ime.** option) t
116d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
116e0 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69  ust supply a sui
116f0 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
11700 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  tion for.** sqli
11710 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
11720 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
11730 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74  ().  An applicat
11740 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20  ion-supplied.** 
11750 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
11760 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
11770 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  t() or sqlite3_o
11780 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20  s_end().** must 
11790 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
117a0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
117b0 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72  d some other [er
117c0 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a  ror code] upon.*
117d0 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e  * failure..*/.in
117e0 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
117f0 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20  lize(void);.int 
11800 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11810 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
11820 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
11830 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
11840 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
11850 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11860 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
11870 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
11880 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
11890 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
118a0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
118b0 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
118c0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
118d0 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
118e0 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
118f0 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
11900 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
11910 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
11920 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
11930 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
11940 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
11950 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
11960 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
11970 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
11980 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
11990 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
119a0 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
119b0 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
119c0 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
119d0 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54  eeds..**.** <b>T
119e0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
119f0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
11a00 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
11a10 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
11a20 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20  .** must ensure 
11a30 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
11a40 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
11a50 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
11a60 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
11a70 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
11a80 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
11a90 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  g.</b>.**.** The
11aa0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11ab0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d  ) interface.** m
11ac0 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
11ad0 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
11ae0 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
11af0 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
11b00 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11b10 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
11b20 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
11b30 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
11b40 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
11b50 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
11b60 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
11b70 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
11b80 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
11b90 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
11ba0 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
11bb0 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
11bc0 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
11bd0 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
11be0 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
11bf0 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
11c00 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
11c10 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
11c20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
11c30 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
11c40 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
11c50 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
11c60 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
11c70 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
11c80 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
11c90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
11ca0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
11cb0 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
11cc0 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
11cd0 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
11ce0 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
11cf0 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
11d00 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
11d10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11d20 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
11d30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
11d40 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
11d50 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11d60 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
11d70 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
11d80 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
11d90 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
11da0 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
11db0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
11dc0 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
11dd0 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
11de0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
11df0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
11e00 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
11e10 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
11e20 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
11e30 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11e40 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
11e50 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  nnections.** MET
11e60 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
11e70 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
11e80 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
11e90 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
11ea0 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
11eb0 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
11ec0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
11ed0 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
11ee0 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
11ef0 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
11f00 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
11f10 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
11f20 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
11f30 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
11f40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11f50 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
11f60 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11f70 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
11f80 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
11f90 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
11fa0 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
11fb0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
11fc0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
11fd0 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
11fe0 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
11ff0 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
12000 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
12010 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
12020 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12030 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
12040 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
12050 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
12060 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
12070 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
12080 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
12090 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
120a0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
120b0 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
120c0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
120d0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
120e0 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
120f0 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
12100 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
12110 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
12120 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
12130 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
12140 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
12150 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
12160 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
12170 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
12180 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
12190 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
121a0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
121b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
121c0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
121d0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
121e0 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
121f0 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
12200 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
12210 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12220 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
12230 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
12240 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
12250 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
12260 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
12270 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
12280 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
12290 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
122a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
122b0 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
122c0 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating 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 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
122f0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
12300 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
12310 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12320 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
12330 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
12340 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
12350 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
12360 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
12370 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
12380 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
12390 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
123a0 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
123b0 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
123c0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
123d0 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
123e0 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
123f0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
12400 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
12410 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
12420 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
12430 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
12440 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
12450 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
12460 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
12470 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
12480 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
12490 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
124a0 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
124b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
124c0 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
124d0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
124e0 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
124f0 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
12500 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
12510 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
12520 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
12530 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
12540 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
12550 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
12560 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
12570 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
12580 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
12590 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
125a0 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
125b0 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
125c0 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
125d0 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
125e0 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
125f0 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
12600 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
12610 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
12620 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
12630 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
12640 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
12650 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
12660 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
12670 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
12680 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
12690 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
126a0 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
126b0 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
126c0 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
126d0 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
126e0 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
126f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
12700 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
12710 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
12720 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
12730 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
12740 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
12750 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
12760 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
12770 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
12780 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
12790 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
127a0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
127b0 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
127c0 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
127d0 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
127e0 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
127f0 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
12800 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
12810 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
12820 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
12830 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12840 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
12850 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
12860 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
12870 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
12880 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
12890 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
128a0 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
128b0 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
128c0 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
128d0 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
128e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
128f0 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
12900 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
12910 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
12920 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
12930 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
12940 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
12950 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
12960 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12970 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
12980 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
12990 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
129a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
129b0 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
129c0 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
129d0 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
129e0 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
129f0 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
12a00 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
12a10 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
12a20 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
12a30 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
12a40 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
12a50 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
12a60 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
12a70 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
12a80 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
12a90 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
12aa0 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
12ab0 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
12ac0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
12ad0 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
12ae0 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
12af0 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
12b00 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
12b10 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
12b20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
12b30 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
12b40 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
12b50 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
12b60 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
12b70 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
12b80 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
12b90 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
12ba0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12bb0 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
12bc0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
12bd0 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
12be0 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
12bf0 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
12c00 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
12c10 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
12c20 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
12c30 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
12c40 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12c50 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
12c60 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
12c70 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
12c80 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
12c90 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
12ca0 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
12cb0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
12cc0 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
12cd0 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
12ce0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
12cf0 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
12d00 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
12d10 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
12d20 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
12d30 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
12d40 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
12d50 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
12d60 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
12d70 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
12d80 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
12d90 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
12da0 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
12db0 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
12dc0 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
12dd0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
12de0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12df0 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
12e00 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
12e10 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12e20 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
12e30 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
12e40 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
12e50 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
12e60 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
12e70 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
12e80 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
12e90 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
12ea0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
12eb0 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
12ec0 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
12ed0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
12ee0 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
12ef0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
12f00 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
12f10 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
12f20 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
12f30 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
12f40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
12f50 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
12f60 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
12f70 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
12f80 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
12f90 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
12fa0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
12fb0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
12fc0 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
12fd0 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
12fe0 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
12ff0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
13000 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
13010 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
13020 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
13030 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
13040 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
13050 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
13060 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
13070 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
13080 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
13090 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
130a0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
130b0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
130c0 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
130d0 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
130e0 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
130f0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
13100 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13110 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
13120 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
13130 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
13140 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
13150 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
13160 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
13170 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
13180 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
13190 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
131a0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
131b0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
131c0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
131d0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
131e0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
131f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13200 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
13210 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
13220 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
13230 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13240 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
13250 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
13260 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
13270 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
13280 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
13290 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
132a0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
132b0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
132c0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
132d0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
132e0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
132f0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
13300 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
13310 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
13320 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
13330 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
13340 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13350 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
13360 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
13370 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
13380 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
13390 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
133a0 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
133b0 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
133c0 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
133d0 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
133e0 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
133f0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13400 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13410 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13420 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13430 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
13440 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13450 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
13460 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
13470 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
13480 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
13490 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
134a0 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
134b0 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
134c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
134d0 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
134e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
134f0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
13500 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
13510 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
13520 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13530 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
13540 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13550 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
13560 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13570 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
13580 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
13590 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
135a0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
135b0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
135c0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
135d0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
135e0 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
135f0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
13600 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
13610 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
13620 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
13630 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
13640 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
13650 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
13660 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
13670 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
13680 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
13690 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
136a0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
136b0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
136c0 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
136d0 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
136e0 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
136f0 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
13700 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
13710 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
13720 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
13730 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
13740 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
13750 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
13760 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13770 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
13780 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
13790 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
137a0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
137b0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
137c0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
137d0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
137e0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
137f0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
13800 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
13810 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
13820 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
13830 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
13840 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
13850 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
13860 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
13870 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
13880 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
13890 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
138a0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
138b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
138c0 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
138d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
138e0 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
138f0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
13900 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
13910 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
13920 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
13930 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
13940 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
13950 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
13960 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
13970 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
13980 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
13990 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
139a0 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
139b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
139c0 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
139d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
139e0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
139f0 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
13a00 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
13a10 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
13a20 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
13a30 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13a40 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
13a50 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
13a60 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
13a70 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
13a80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13a90 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
13aa0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
13ab0 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
13ac0 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
13ad0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
13ae0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13af0 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
13b00 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
13b10 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
13b20 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
13b30 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
13b40 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
13b50 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13b60 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
13b70 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
13b80 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
13b90 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
13ba0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
13bb0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
13bc0 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
13bd0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
13be0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
13bf0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13c00 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
13c10 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
13c20 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
13c30 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
13c40 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
13c50 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
13c60 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13c70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
13c80 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
13c90 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
13ca0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
13cb0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
13cc0 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
13cd0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13ce0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
13cf0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
13d00 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
13d10 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
13d20 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
13d30 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
13d40 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
13d50 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
13d60 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
13d70 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
13d80 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
13d90 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
13da0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13db0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
13dc0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
13dd0 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
13de0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
13df0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
13e00 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
13e10 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13e20 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
13e30 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
13e40 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
13e50 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
13e60 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13e70 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
13e80 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13e90 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
13ea0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
13eb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13ec0 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  TMALLOC option t
13ed0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13ee0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
13ef0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
13f00 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13f10 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
13f20 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13f30 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  re..** The [sqli
13f40 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13f50 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
13f60 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
13f70 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
13f80 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
13f90 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
13fa0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
13fb0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
13fc0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
13fd0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
13fe0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
13ff0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
14000 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
14010 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
14020 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
14030 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
14040 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
14050 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
14060 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14070 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  SMALL_MALLOC]] <
14080 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14090 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64  _SMALL_MALLOC</d
140a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
140b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
140c0 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  ALL_MALLOC optio
140d0 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
140e0 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79  rgument of.** ty
140f0 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
14100 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
14110 2c 20 77 68 69 63 68 20 69 66 20 74 72 75 65 20  , which if true 
14120 70 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74 20  provides a hint 
14130 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 61  to.** SQLite tha
14140 74 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f 69  t it should avoi
14150 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61  d large memory a
14160 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 6f  llocations if po
14170 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74  ssible..** SQLit
14180 65 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 65  e will run faste
14190 72 20 69 66 20 69 74 20 69 73 20 66 72 65 65 20  r if it is free 
141a0 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65  to make large me
141b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
141c0 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 70  ,.** but some ap
141d0 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
141e0 70 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73 6c  prefer to run sl
141f0 6f 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67 65  ower in exchange
14200 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65   for.** guarante
14210 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20  es about memory 
14220 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68  fragmentation th
14230 61 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65 20  at are possible 
14240 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f  if large.** allo
14250 63 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f 69  cations are avoi
14260 64 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ded.  This hint 
14270 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e  is normally off.
14280 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
14290 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
142a0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
142b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
142c0 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
142d0 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
142e0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
142f0 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  S option takes s
14300 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
14310 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69  f type int,.** i
14320 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
14330 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
14340 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
14350 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
14360 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  n of.** memory a
14370 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14380 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
14390 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
143a0 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a  tatistics are.**
143b0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
143c0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
143d0 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
143e0 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
143f0 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
14400 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
14410 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
14420 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
14430 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
14440 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
14450 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
14460 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
14470 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
14480 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20  _status64()].** 
14490 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
144a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
144b0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
144c0 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
144d0 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
144e0 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
144f0 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
14500 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
14510 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
14520 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
14530 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
14540 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
14550 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
14560 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14570 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
14580 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14590 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
145a0 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
145b0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
145c0 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c  H option is no l
145d0 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c  onger used..** <
145e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
145f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
14600 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
14610 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
14620 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
14630 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14640 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74  IG_PAGECACHE opt
14650 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
14660 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74  memory pool.** t
14670 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
14680 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
14690 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
146a0 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
146b0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
146c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
146d0 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
146e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
146f0 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70  a no-op if an ap
14700 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
14710 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
14720 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
14730 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
14740 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
14750 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54  _PCACHE2]..** ^T
14760 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
14770 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
14780 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
14790 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  CHE: A pointer t
147a0 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67  o.** 8-byte alig
147b0 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d  ned memory (pMem
147c0 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  ), the size of e
147d0 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c  ach page cache l
147e0 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ine (sz),.** and
147f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
14800 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a  ache lines (N)..
14810 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
14820 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
14830 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
14840 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
14850 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
14860 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
14870 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75  2 and 65536) plu
14880 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74  s some extra byt
14890 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  es for each.** p
148a0 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
148b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
148c0 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62  a bytes needed b
148d0 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65  y the page heade
148e0 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  r.** can be dete
148f0 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51  rmined using [SQ
14900 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14910 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49  HE_HDRSZ]..** ^I
14920 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
14930 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
14940 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
14950 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d  for the sz param
14960 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65  eter to be large
14970 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79  r than necessary
14980 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61  .  The pMem.** a
14990 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
149a0 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
149b0 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74  inter or a point
149c0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  er to an 8-byte.
149d0 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b  ** aligned block
149e0 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74   of memory of at
149f0 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
14a00 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20  s, otherwise.** 
14a10 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
14a20 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
14a30 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20  ..** ^When pMem 
14a40 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
14a50 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20  ite will strive 
14a60 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  to use the memor
14a70 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f  y provided.** to
14a80 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61   satisfy page ca
14a90 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69  che needs, falli
14aa0 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69  ng back to [sqli
14ab0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66  te3_malloc()] if
14ac0 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65  .** a page cache
14ad0 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20   line is larger 
14ae0 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72  than sz bytes or
14af0 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70   if all of the p
14b00 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  Mem buffer.** is
14b10 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e   exhausted..** ^
14b20 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20  If pMem is NULL 
14b30 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72  and N is non-zer
14b40 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74  o, then each dat
14b50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14b60 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74  .** does an init
14b70 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74  ial bulk allocat
14b80 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63  ion for page cac
14b90 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f  he memory.** fro
14ba0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
14bb0 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20  c()] sufficient 
14bc0 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65  for N cache line
14bd0 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  s if N is positi
14be0 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32  ve or.** of -102
14bf0 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69  4*N bytes if N i
14c00 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49  s negative, . ^I
14c10 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
14c20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
14c30 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
14c40 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
14c50 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69  ded by the initi
14c60 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  al.** allocation
14c70 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f  , then SQLite go
14c80 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
14c90 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74  alloc()] separat
14ca0 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ely for each.** 
14cb0 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65  additional cache
14cc0 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   line. </dd>.**.
14cd0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14ce0 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
14cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14d00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
14d10 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14d20 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65  _HEAP option spe
14d30 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
14d40 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a  memory buffer .*
14d50 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  * that SQLite wi
14d60 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  ll use for all o
14d70 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
14d80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14d90 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20  needs.** beyond 
14da0 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66  those provided f
14db0 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
14dc0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
14dd0 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
14de0 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
14df0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
14e00 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
14e10 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
14e20 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  th either [SQLIT
14e30 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
14e40 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ] or [SQLITE_ENA
14e50 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64  BLE_MEMSYS5] and
14e60 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
14e70 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e  ITE_ERROR] if in
14e80 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e  voked otherwise.
14e90 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
14ea0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
14eb0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
14ec0 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79  HEAP:.** An 8-by
14ed0 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
14ee0 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
14ef0 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
14f00 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
14f10 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
14f20 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
14f30 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
14f40 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
14f50 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
14f60 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
14f70 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
14f80 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
14f90 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
14fa0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
14fb0 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
14fc0 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
14fd0 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
14fe0 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
14ff0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
15000 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
15010 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
15020 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
15030 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
15040 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
15050 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
15060 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
15070 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
15080 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
15090 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
150a0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
150b0 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
150c0 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
150d0 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
150e0 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
150f0 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
15100 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
15110 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
15120 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
15130 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
15140 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
15150 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73  d at 2**12. Reas
15160 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a  onable values.**
15170 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d   for the minimum
15180 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
15190 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67   are 2**5 throug
151a0 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  h 2**8.</dd>.**.
151b0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
151c0 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  IG_MUTEX]] <dt>S
151d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
151e0 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
151f0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
15200 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e  FIG_MUTEX option
15210 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15220 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
15230 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
15240 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
15250 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
15260 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
15270 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
15280 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
15290 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  s alternative lo
152a0 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
152b0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
152c0 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68  d.** in place th
152d0 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
152e0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
152f0 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
15300 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  akes a copy of.*
15310 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
15320 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
15330 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
15340 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
15350 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
15360 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
15370 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
15380 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
15390 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
153a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
153b0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
153c0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
153d0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
153e0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
153f0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
15400 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
15410 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
15420 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
15430 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15440 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
15450 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
15460 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15470 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
15480 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
15490 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
154a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
154b0 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
154c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
154d0 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
154e0 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
154f0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f  ONFIG_GETMUTEX o
15500 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
15510 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
15520 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
15530 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
15540 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
15550 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
15560 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
15570 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
15580 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
15590 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
155a0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
155b0 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
155c0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
155d0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
155e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
155f0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
15600 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
15610 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
15620 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
15630 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
15640 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
15650 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
15660 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
15670 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
15680 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
15690 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
156a0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
156b0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
156c0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
156d0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
156e0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
156f0 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
15700 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
15710 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
15720 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
15730 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
15740 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
15750 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
15760 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
15770 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15780 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
15790 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
157a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
157b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
157c0 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
157d0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
157e0 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
157f0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
15800 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70  FIG_LOOKASIDE op
15810 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
15820 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
15830 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64  termine.** the d
15840 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c  efault size of l
15850 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
15860 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73  on each [databas
15870 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
15880 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
15890 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
158a0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
158b0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
158c0 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
158d0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
158e0 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
158f0 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
15900 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15910 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f  .)^  ^(SQLITE_CO
15920 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a  NFIG_LOOKASIDE.*
15930 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65  * sets the <i>de
15940 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
15950 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
15960 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15970 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74  OOKASIDE].** opt
15980 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ion to [sqlite3_
15990 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
159a0 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
159b0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
159c0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
159d0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
159e0 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
159f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
15a00 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15a10 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
15a20 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f  CONFIG_PCACHE2</
15a30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
15a40 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15a50 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
15a60 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
15a70 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
15a80 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
15a90 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
15aa0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
15ab0 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
15ac0 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ct specifies.** 
15ad0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  the interface to
15ae0 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
15af0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
15b00 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74  ion.)^.** ^SQLit
15b10 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
15b20 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  f the [sqlite3_p
15b30 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
15b40 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
15b50 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15b60 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
15b70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15b80 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
15b90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
15ba0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15bb0 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  TPCACHE2 option 
15bc0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
15bd0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
15be0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
15bf0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
15c00 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
15c10 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
15c20 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63  pies of.** the c
15c30 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68  urrent page cach
15c40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
15c50 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
15c60 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
15c70 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15c80 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
15c90 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
15ca0 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
15cb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
15cc0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
15cd0 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
15ce0 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
15cf0 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
15d00 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
15d10 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
15d20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
15d30 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
15d40 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
15d50 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
15d60 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
15d70 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
15d80 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
15d90 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
15da0 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
15db0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
15dc0 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
15dd0 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
15de0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
15df0 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
15e00 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
15e10 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
15e20 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
15e30 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
15e40 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
15e50 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
15e60 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
15e70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
15e80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
15e90 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
15ea0 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
15eb0 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
15ec0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
15ed0 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
15ee0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
15ef0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
15f00 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
15f10 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
15f20 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
15f30 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
15f40 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
15f50 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
15f60 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
15f70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
15f80 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
15f90 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
15fa0 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
15fb0 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
15fc0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
15fd0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
15fe0 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
15ff0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16000 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
16010 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
16020 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
16030 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
16040 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
16050 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
16060 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
16070 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
16080 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
16090 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
160a0 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
160b0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
160c0 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
160d0 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
160e0 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
160f0 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
16100 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
16110 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
16120 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
16130 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
16140 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
16150 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
16160 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16170 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
16180 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
16190 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74  FIG_URI option t
161a0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
161b0 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
161c0 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65  nt..** If non-ze
161d0 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
161e0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
161f0 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
16200 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
16210 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49  ero,.** then URI
16220 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
16230 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29  bally disabled.)
16240 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69  ^ ^If URI handli
16250 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
16260 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  * enabled, all f
16270 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20  ilenames passed 
16280 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
16290 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
162a0 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  en_v2()],.** [sq
162b0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
162c0 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
162d0 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
162e0 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
162f0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
16300 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
16310 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
16320 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
16330 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
16340 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
16350 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
16360 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
16370 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f  d. ^If it is glo
16380 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
16390 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
163a0 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
163b0 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
163c0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
163d0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
163e0 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
163f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
16400 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66  opened. ^(By def
16410 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
16420 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
16430 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
16440 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
16450 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
16460 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
16470 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
16480 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
16490 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  fined.)^.**.** [
164a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
164b0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
164c0 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
164d0 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
164e0 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
164f0 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
16500 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
16510 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20  DEX_SCAN option 
16520 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69  takes a single i
16530 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65  nteger.** argume
16540 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
16550 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
16560 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f  lean in order to
16570 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
16580 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  le.** the use of
16590 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
165a0 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
165b0 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75   scans in the qu
165c0 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a  ery optimizer..*
165d0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
165e0 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
165f0 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  ined.** by the [
16600 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56  SQLITE_ALLOW_COV
16610 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
16620 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16630 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e  ption, or is "on
16640 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d  ".** if that com
16650 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
16660 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20   is omitted..** 
16670 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64  The ability to d
16680 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
16690 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
166a0 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
166b0 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65  e scans.** is be
166c0 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72  cause some incor
166d0 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67  rectly coded leg
166e0 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  acy applications
166f0 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69   might malfuncti
16700 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f  on.** when the o
16710 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65  ptimization is e
16720 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69  nabled.  Providi
16730 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  ng the ability t
16740 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65  o.** disable the
16750 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c   optimization al
16760 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20  lows the older, 
16770 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f  buggy applicatio
16780 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a  n code to work.*
16790 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65  * without change
167a0 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72   even with newer
167b0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
167c0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ite..**.** [[SQL
167d0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
167e0 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  E]] [[SQLITE_CON
167f0 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a  FIG_GETPCACHE]].
16800 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16810 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20  NFIG_PCACHE and 
16820 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16830 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
16840 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
16850 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
16860 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
16870 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
16880 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
16890 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
168a0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
168b0 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
168c0 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ps..** </dd>.**.
168d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
168e0 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c  IG_SQLLOG]].** <
168f0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16900 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54  _SQLLOG.** <dd>T
16910 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
16920 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
16930 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  sqlite is compil
16940 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
16950 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51  SQLITE_ENABLE_SQ
16960 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOG] pre-proces
16970 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  sor macro define
16980 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
16990 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  ument should.** 
169a0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
169b0 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
169c0 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  pe void(*)(void*
169d0 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20  ,sqlite3*,const 
169e0 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20  char*, int)..** 
169f0 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c  The second shoul
16a00 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f  d be of type (vo
16a10 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61  id*). The callba
16a20 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  ck is invoked by
16a30 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20   the library.** 
16a40 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74  in three separat
16a50 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
16a60 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
16a70 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
16a80 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
16a90 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74   parameter. If t
16aa0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
16ab0 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74  ter is 0, then t
16ac0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
16ad0 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64  ection.** passed
16ae0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
16af0 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74  rgument has just
16b00 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68   been opened. Th
16b10 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
16b20 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  .** points to a 
16b30 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e  buffer containin
16b40 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  g the name of th
16b50 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
16b60 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20  file. If the.** 
16b70 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
16b80 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20   is 1, then the 
16b90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
16ba0 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72  at the third par
16bb0 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73  ameter.** points
16bc0 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65   to has just bee
16bd0 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20  n executed. Or, 
16be0 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  if the fourth pa
16bf0 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68  rameter is 2, th
16c00 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63  en.** the connec
16c10 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65  tion being passe
16c20 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
16c30 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69  parameter is bei
16c40 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a  ng closed. The.*
16c50 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
16c60 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c  r is passed NULL
16c70 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20   In this case.  
16c80 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73  An example of us
16c90 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66  ing this.** conf
16ca0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16cb0 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20   can be seen in 
16cc0 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67  the "test_sqllog
16cd0 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20  .c" source file 
16ce0 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69  in.** the canoni
16cf0 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63  cal SQLite sourc
16d00 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e tree.</dd>.**.
16d10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16d20 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  IG_MMAP_SIZE]].*
16d30 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16d40 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a  FIG_MMAP_SIZE.**
16d50 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e   <dd>^SQLITE_CON
16d60 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61  FIG_MMAP_SIZE ta
16d70 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69  kes two 64-bit i
16d80 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f  nteger (sqlite3_
16d90 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a  int64) values.**
16da0 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65   that are the de
16db0 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20  fault mmap size 
16dc0 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75  limit (the defau
16dd0 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a  lt setting for.*
16de0 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  * [PRAGMA mmap_s
16df0 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61  ize]) and the ma
16e00 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
16e10 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a  ap size limit..*
16e20 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
16e30 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76  etting can be ov
16e40 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68  erridden by each
16e50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16e60 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69  tion using.** ei
16e70 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41  ther the [PRAGMA
16e80 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d   mmap_size] comm
16e90 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67  and, or by using
16ea0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
16eb0 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
16ec0 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20   file control.  
16ed0 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  ^(The maximum al
16ee0 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a  lowed mmap size.
16ef0 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e  ** will be silen
16f00 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66  tly truncated if
16f10 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68   necessary so th
16f20 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65  at it does not e
16f30 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  xceed the.** com
16f40 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75  pile-time maximu
16f50 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20  m mmap size set 
16f60 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
16f70 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d  E_MAX_MMAP_SIZE]
16f80 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
16f90 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65  tion.)^.** ^If e
16fa0 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74  ither argument t
16fb0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  o this option is
16fc0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
16fd0 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73  that argument is
16fe0 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69  .** changed to i
16ff0 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ts compile-time 
17000 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b  default..**.** [
17010 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  [SQLITE_CONFIG_W
17020 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a  IN32_HEAPSIZE]].
17030 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
17040 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
17050 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  IZE.** <dd>^The 
17060 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
17070 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74  N32_HEAPSIZE opt
17080 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
17090 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
170a0 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66  is.** compiled f
170b0 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20  or Windows with 
170c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33  the [SQLITE_WIN3
170d0 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72  2_MALLOC] pre-pr
170e0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a  ocessor macro.**
170f0 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54   defined. ^SQLIT
17100 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
17110 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
17120 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
17130 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
17140 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
17150 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
17160 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
17170 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  heap..**.** [[SQ
17180 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17190 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64  HE_HDRSZ]].** <d
171a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
171b0 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20  PCACHE_HDRSZ.** 
171c0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
171d0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
171e0 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  RSZ option takes
171f0 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
17200 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
17210 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
17220 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74  integer and writ
17230 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  es into that int
17240 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20  eger the number 
17250 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65  of extra.** byte
17260 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69  s per page requi
17270 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67  red for each pag
17280 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e in [SQLITE_CON
17290 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
172a0 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ** The amount of
172b0 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71   extra space req
172c0 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65  uired can change
172d0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
172e0 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74  e compiler,.** t
172f0 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20  arget platform, 
17300 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
17310 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  on..**.** [[SQLI
17320 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d  TE_CONFIG_PMASZ]
17330 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
17340 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20  CONFIG_PMASZ.** 
17350 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
17360 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74  CONFIG_PMASZ opt
17370 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
17380 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
17390 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69  ch.** is an unsi
173a0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
173b0 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d   sets the "Minim
173c0 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72  um PMA Size" for
173d0 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64   the multithread
173e0 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20  ed.** sorter to 
173f0 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54  that integer.  T
17400 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d  he default minim
17410 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73  um PMA Size is s
17420 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
17430 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53  LITE_SORTER_PMAS
17440 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  Z] compile-time 
17450 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72  option.  New thr
17460 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65  eads are launche
17470 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74  d.** to help wit
17480 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e  h sort operation
17490 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65  s when multithre
174a0 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20  aded sorting.** 
174b0 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e  is enabled (usin
174c0 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68  g the [PRAGMA th
174d0 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20  reads] command) 
174e0 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  and the amount o
174f0 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20  f content.** to 
17500 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64  be sorted exceed
17510 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20  s the page size 
17520 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75  times the minimu
17530 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41  m of the.** [PRA
17540 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20  GMA cache_size] 
17550 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73  setting and this
17560 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   value..**.** [[
17570 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
17580 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a  MTJRNL_SPILL]].*
17590 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
175a0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
175b0 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  LL.** <dd>^The S
175c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
175d0 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69  TJRNL_SPILL opti
175e0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
175f0 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
17600 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65  h.** becomes the
17610 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [statement jour
17620 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69  nal] spill-to-di
17630 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a  sk threshold.  .
17640 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f  ** [Statement jo
17650 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64  urnals] are held
17660 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c   in memory until
17670 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20   their size (in 
17680 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64  bytes).** exceed
17690 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64  s this threshold
176a0 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74  , at which point
176b0 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65   they are writte
176c0 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72  n to disk..** Or
176d0 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c   if the threshol
176e0 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65  d is -1, stateme
176f0 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20  nt journals are 
17700 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65  always held.** e
17710 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65  xclusively in me
17720 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d  mory..** Since m
17730 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f  any statement jo
17740 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63  urnals never bec
17750 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69  ome large, setti
17760 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20  ng the spill.** 
17770 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76  threshold to a v
17780 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b  alue such as 64K
17790 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72  iB can greatly r
177a0 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74  educe the amount
177b0 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69   of.** I/O requi
177c0 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73  red to support s
177d0 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63  tatement rollbac
177e0 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  k..** The defaul
177f0 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73  t value for this
17800 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74   setting is cont
17810 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  rolled by the.**
17820 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e   [SQLITE_STMTJRN
17830 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65  L_SPILL] compile
17840 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
17850 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
17860 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17870 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
17880 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
17890 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
178a0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
178b0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
178c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
178d0 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
178e0 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
178f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17900 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
17910 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
17920 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
17930 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17940 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
17950 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
17960 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
17970 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17980 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
17990 20 20 20 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f       6  /* No lo
179a0 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65  nger used */.#de
179b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
179c0 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20  IG_PAGECACHE    
179d0 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   7  /* void*, in
179e0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
179f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17a00 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20  NFIG_HEAP       
17a10 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     8  /* void*, 
17a20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d  int nByte, int m
17a30 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  in */.#define SQ
17a40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
17a50 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20  TATUS     9  /* 
17a60 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69  boolean */.#defi
17a70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17a80 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30  _MUTEX        10
17a90 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
17aa0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  ex_methods* */.#
17ab0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17ac0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20  NFIG_GETMUTEX   
17ad0 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33    11  /* sqlite3
17ae0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
17af0 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79  */./* previously
17b00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
17b10 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69  HUNKALLOC 12 whi
17b20 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64  ch is now unused
17b30 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51  . */ .#define SQ
17b40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
17b50 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20  ASIDE    13  /* 
17b60 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69  int int */.#defi
17b70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17b80 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34  _PCACHE       14
17b90 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
17ba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17bb0 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20  FIG_GETPCACHE   
17bc0 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   15  /* no-op */
17bd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17be0 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
17bf0 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
17c00 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
17c10 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17c20 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37  _URI          17
17c30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
17c40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17c50 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31  G_PCACHE2      1
17c60 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  8  /* sqlite3_pc
17c70 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
17c80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17c90 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
17ca0 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69  E2   19  /* sqli
17cb0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
17cc0 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
17cd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
17ce0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
17cf0 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a  N 20  /* int */.
17d00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17d10 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20  ONFIG_SQLLOG    
17d20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f     21  /* xSqllo
17d30 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  g, void* */.#def
17d40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17d50 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32  G_MMAP_SIZE    2
17d60 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e  2  /* sqlite3_in
17d70 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  t64, sqlite3_int
17d80 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  64 */.#define SQ
17d90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
17da0 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20  2_HEAPSIZE      
17db0 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  23  /* int nByte
17dc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17dd0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
17de0 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34  _HDRSZ        24
17df0 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f    /* int *psz */
17e00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17e10 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20  CONFIG_PMASZ    
17e20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f             25  /
17e30 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73  * unsigned int s
17e40 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20  zPma */.#define 
17e50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
17e60 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20  MTJRNL_SPILL    
17e70 20 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79    26  /* int nBy
17e80 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
17e90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c  LITE_CONFIG_SMAL
17ea0 4c 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  L_MALLOC        
17eb0 32 37 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a  27  /* boolean *
17ec0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
17ed0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
17ee0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
17ef0 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
17f00 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
17f10 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
17f20 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
17f30 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17f40 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
17f50 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
17f60 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
17f70 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
17f80 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
17f90 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
17fa0 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
17fb0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
17fc0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
17fd0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
17fe0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
17ff0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
18000 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
18010 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
18020 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
18030 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
18040 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
18050 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
18060 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
18070 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
18080 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
18090 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
180a0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
180b0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
180c0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
180d0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
180e0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
180f0 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
18100 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
18110 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
18120 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
18130 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
18140 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
18150 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
18160 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
18170 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
18180 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
18190 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
181a0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
181b0 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
181c0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
181d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
181e0 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
181f0 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
18200 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
18210 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
18220 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
18230 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
18240 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
18250 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
18260 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
18270 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18280 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
18290 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
182a0 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
182b0 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
182c0 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
182d0 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
182e0 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
182f0 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
18300 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
18310 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
18320 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
18330 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
18340 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
18350 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
18360 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
18370 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
18380 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
18390 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
183a0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
183b0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
183c0 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
183d0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
183e0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
183f0 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
18400 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
18410 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
18420 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
18430 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
18440 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
18450 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
18460 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
18470 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
18480 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
18490 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
184a0 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
184b0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
184c0 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
184d0 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
184e0 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
184f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
18500 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
18510 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
18520 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
18530 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
18540 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
18550 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
18560 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
18570 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
18580 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
18590 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
185a0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
185b0 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
185c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
185d0 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
185e0 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
185f0 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
18600 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
18610 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
18620 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
18630 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
18640 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
18650 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
18660 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
18670 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
18680 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
18690 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
186a0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
186b0 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
186c0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
186d0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
186e0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
186f0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
18700 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
18710 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
18720 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
18730 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
18740 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
18750 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
18760 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
18770 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
18780 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
18790 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
187a0 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
187b0 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
187c0 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
187d0 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
187e0 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
187f0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
18800 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
18810 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
18820 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
18830 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
18840 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
18850 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
18860 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
18870 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
18880 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
18890 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
188a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
188b0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
188c0 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
188d0 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
188e0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
188f0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
18900 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
18910 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
18920 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
18930 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
18940 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
18950 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
18960 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
18970 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
18980 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
18990 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
189a0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
189b0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
189c0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
189d0 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
189e0 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
189f0 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
18a00 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
18a10 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
18a20 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
18a30 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
18a40 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
18a50 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
18a60 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
18a70 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
18a80 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
18a90 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
18aa0 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
18ab0 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
18ac0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
18ad0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18ae0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
18af0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
18b00 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
18b10 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
18b20 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
18b30 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
18b40 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
18b50 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
18b60 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64  TS3_TOKENIZER</d
18b70 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
18b80 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
18b90 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
18ba0 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67  able the two-arg
18bb0 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e  ument.** version
18bc0 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f   of the [fts3_to
18bd0 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74  kenizer()] funct
18be0 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61 72  ion which is par
18bf0 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53  t of the.** [FTS
18c00 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61  3] full-text sea
18c10 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e  rch engine exten
18c20 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73  sion..** There s
18c30 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
18c40 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
18c50 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
18c60 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
18c70 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
18c80 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73  0 to disable fts
18c90 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72  3_tokenizer() or
18ca0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
18cb0 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65  enable fts3_toke
18cc0 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74  nizer() or negat
18cd0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
18ce0 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68   setting.** unch
18cf0 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
18d00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
18d10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
18d20 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
18d30 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
18d40 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
18d50 69 63 61 74 65 20 77 68 65 74 68 65 72 20 66 74  icate whether ft
18d60 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20  s3_tokenizer is 
18d70 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
18d80 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
18d90 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
18da0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18db0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
18dc0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
18dd0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65  hich case the ne
18de0 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  w setting is not
18df0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
18e00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
18e10 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18e20 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45  ENABLE_LOAD_EXTE
18e30 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  NSION</dt>.** <d
18e40 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
18e50 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
18e60 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
18e70 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
18e80 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69  xtension()].** i
18e90 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e  nterface indepen
18ea0 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c  dently of the [l
18eb0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18ec0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
18ed0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65  * The [sqlite3_e
18ee0 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
18ef0 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62  sion()] API enab
18f00 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
18f10 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50  both the.** C-AP
18f20 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  I [sqlite3_load_
18f30 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64  extension()] and
18f40 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
18f50 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  n [load_extensio
18f60 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  n()]..** There s
18f70 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
18f80 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
18f90 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66  s..** When the f
18fa0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
18fb0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
18fc0 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20  is 1, then only 
18fd0 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20  the C-API is.** 
18fe0 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20  enabled and the 
18ff0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d  SQL function rem
19000 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20  ains disabled.  
19010 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67  If the first arg
19020 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73  ument to.** this
19030 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c   interface is 0,
19040 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43   then both the C
19050 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c  -API and the SQL
19060 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69   function are di
19070 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68  sabled..** If th
19080 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19090 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20   is -1, then no 
190a0 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65  changes are made
190b0 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74   to state of eit
190c0 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49  her the.** C-API
190d0 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63   or the SQL func
190e0 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63  tion..** The sec
190f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
19100 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
19110 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
19120 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
19130 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
19140 63 61 74 65 20 77 68 65 74 68 65 72 20 5b 73 71  cate whether [sq
19150 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
19160 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63  sion()] interfac
19170 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64  e.** is disabled
19180 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c   or enabled foll
19190 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
191a0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
191b0 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65  ameter may.** be
191c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
191d0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74   in which case t
191e0 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69  he new setting i
191f0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
19200 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ack..** </dd>.**
19210 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
19220 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41  BCONFIG_MAINDBNA
19230 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ME</dt>.** <dd> 
19240 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
19250 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
19260 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 22  he name of the "
19270 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65 0a 2a  main" database.*
19280 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68 65 20  * schema.  ^The 
19290 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20 69 73  sole argument is
192a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
192b0 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20 73 74  constant UTF8 st
192c0 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77 69  ring.** which wi
192d0 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 6e 65  ll become the ne
192e0 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e  w schema name in
192f0 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e 22   place of "main"
19300 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f  .  ^SQLite.** do
19310 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f  es not make a co
19320 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20 6d 61  py of the new ma
19330 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 73  in schema name s
19340 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20 61 70  tring, so the ap
19350 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
19360 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
19370 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  e argument passe
19380 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42 43 4f  d into this DBCO
19390 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73 20 75  NFIG option is u
193a0 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69  nchanged.** unti
193b0 6c 20 61 66 74 65 72 20 74 68 65 20 64 61 74 61  l after the data
193c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
193d0 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  closes..** </dd>
193e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
193f0 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b  E_DBCONFIG_NO_CK
19400 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e  PT_ON_CLOSE</dt>
19410 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79  .** <dd> Usually
19420 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  , when a databas
19430 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73  e in wal mode is
19440 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74 61 63   closed or detac
19450 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64  hed from a .** d
19460 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2c 20  atabase handle, 
19470 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20 69 66  SQLite checks if
19480 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20   this will mean 
19490 74 68 61 74 20 74 68 65 72 65 20 61 72 65 20 6e  that there are n
194a0 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63  ow no .** connec
194b0 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20  tions at all to 
194c0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 49 66  the database. If
194d0 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d 73   so, it performs
194e0 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a   a checkpoint .*
194f0 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65 66 6f  * operation befo
19500 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 63  re closing the c
19510 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73 20  onnection. This 
19520 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 73  option may be us
19530 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64  ed to.** overrid
19540 65 20 74 68 69 73 20 62 65 68 61 76 69 6f 75 72  e this behaviour
19550 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  . The first para
19560 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
19570 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a  this operation.*
19580 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  * is an integer 
19590 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64 69  - non-zero to di
195a0 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74  sable checkpoint
195b0 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a  s-on-close, or z
195c0 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66 61  ero (the.** defa
195d0 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65 20 74  ult) to enable t
195e0 68 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  hem. The second 
195f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
19600 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
19610 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69  eger.** into whi
19620 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ch is written 0 
19630 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
19640 20 77 68 65 74 68 65 72 20 63 68 65 63 6b 70 6f   whether checkpo
19650 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a  ints-on-close.**
19660 20 68 61 76 65 20 62 65 65 6e 20 64 69 73 61 62   have been disab
19670 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65 79 20  led - 0 if they 
19680 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c 65 64  are not disabled
19690 2c 20 31 20 69 66 20 74 68 65 79 20 61 72 65 2e  , 1 if they are.
196a0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 64 74  .** </dd>.** <dt
196b0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
196c0 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74  _ENABLE_QPSG</dt
196d0 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  >.** <dd>^(The S
196e0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
196f0 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f  NABLE_QPSG optio
19700 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 64  n activates or d
19710 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68  eactivates.** th
19720 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  e [query planner
19730 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 61   stability guara
19740 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57  ntee] (QPSG).  W
19750 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 20  hen the QPSG is 
19760 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e  active,.** a sin
19770 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 74  gle SQL query st
19780 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77  atement will alw
19790 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65  ays use the same
197a0 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72   algorithm regar
197b0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75  dless.** of valu
197c0 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  es of [bound par
197d0 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20  ameters].)^ The 
197e0 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f  QPSG disables so
197f0 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  me query optimiz
19800 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c  ations.** that l
19810 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65  ook at the value
19820 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d  s of bound param
19830 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e  eters, which can
19840 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69   make some queri
19850 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42  es.** slower.  B
19860 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73 20  ut the QPSG has 
19870 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66  the advantage of
19880 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c   more predictabl
19890 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74  e behavior.  Wit
198a0 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63  h.** the QPSG ac
198b0 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c  tive, SQLite wil
198c0 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 65  l always use the
198d0 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e   same query plan
198e0 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73   in the field as
198f0 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 72  .** was used dur
19900 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74  ing testing in t
19910 68 65 20 6c 61 62 2e 0a 2a 2a 20 3c 2f 64 64 3e  he lab..** </dd>
19920 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
19930 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f  BCONFIG_TRIGGER_
19940 45 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EQP</dt>.** <dd>
19950 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
19960 20 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41   output of EXPLA
19970 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f  IN QUERY PLAN co
19980 6d 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20  mmands does not 
19990 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70  .** include outp
199a0 75 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61  ut for any opera
199b0 74 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20  tions performed 
199c0 62 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  by trigger progr
199d0 61 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74  ams. This.** opt
199e0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73  ion is used to s
199f0 65 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65  et or clear (the
19a00 20 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67   default) a flag
19a10 20 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68   that governs th
19a20 69 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20  is.** behavior. 
19a30 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
19a40 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
19a50 69 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  is operation is 
19a60 61 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20  an integer -.** 
19a70 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 65 6e 61 62  non-zero to enab
19a80 6c 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72  le output for tr
19a90 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20  igger programs, 
19aa0 6f 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62  or zero to disab
19ab0 6c 65 20 69 74 2e 0a 2a 2a 20 54 68 65 20 73 65  le it..** The se
19ac0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
19ad0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
19ae0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
19af0 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20  hich is written 
19b00 0a 2a 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  .** 0 or 1 to in
19b10 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 6f  dicate whether o
19b20 75 74 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65  utput-for-trigge
19b30 72 73 20 68 61 73 20 62 65 65 6e 20 64 69 73 61  rs has been disa
19b40 62 6c 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20  bled - 0 if .** 
19b50 69 74 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c  it is not disabl
19b60 65 64 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20  ed, 1 if it is. 
19b70 20 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f   .** </dd>.** </
19b80 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
19b90 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d  QLITE_DBCONFIG_M
19ba0 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20  AINDBNAME       
19bb0 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e       1000 /* con
19bc0 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66  st char* */.#def
19bd0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
19be0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
19bf0 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f            1001 /
19c00 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
19c10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19c20 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19c30 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20  E_FKEY          
19c40 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74   1002 /* int int
19c50 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
19c60 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19c70 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  BLE_TRIGGER     
19c80 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69     1003 /* int i
19c90 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
19ca0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
19cb0 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e  NABLE_FTS3_TOKEN
19cc0 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74  IZER 1004 /* int
19cd0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
19ce0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19cf0 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54  _ENABLE_LOAD_EXT
19d00 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69  ENSION 1005 /* i
19d10 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
19d20 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
19d30 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c  IG_NO_CKPT_ON_CL
19d40 4f 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a  OSE      1006 /*
19d50 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
19d60 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
19d70 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47  NFIG_ENABLE_QPSG
19d80 20 20 20 20 20 20 20 20 20 20 20 31 30 30 37 20             1007 
19d90 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
19da0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
19db0 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45  CONFIG_TRIGGER_E
19dc0 51 50 20 20 20 20 20 20 20 20 20 20 20 31 30 30  QP           100
19dd0 38 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  8 /* int int* */
19de0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19df0 44 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20 20  DBCONFIG_MAX    
19e00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
19e10 30 30 38 20 2f 2a 20 4c 61 72 67 65 73 74 20 44  008 /* Largest D
19e20 42 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a  BCONFIG */../*.*
19e30 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
19e40 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
19e50 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
19e60 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
19e70 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
19e80 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
19e90 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
19ea0 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
19eb0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
19ec0 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
19ed0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
19ee0 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
19ef0 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
19f00 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
19f10 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
19f20 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
19f30 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
19f40 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
19f50 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
19f60 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
19f70 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
19f80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19f90 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
19fa0 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
19fb0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  ite3.**.** ^Each
19fc0 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
19fd0 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
19fe0 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
19ff0 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
1a000 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
1a010 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
1a020 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
1a030 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
1a040 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
1a050 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
1a060 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
1a070 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
1a080 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
1a090 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
1a0a0 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
1a0b0 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
1a0c0 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
1a0d0 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
1a0e0 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
1a0f0 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
1a100 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
1a110 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
1a120 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
1a130 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
1a140 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
1a150 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
1a160 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1a170 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1a180 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
1a190 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73   usually returns
1a1a0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a   the [rowid] of.
1a1b0 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ** the most rece
1a1c0 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  nt successful [I
1a1d0 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f  NSERT] into a ro
1a1e0 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69  wid table or [vi
1a1f0 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
1a200 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  on database conn
1a210 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72  ection D. ^Inser
1a220 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
1a230 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
1a240 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64  re not.** record
1a250 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  ed. ^If no succe
1a260 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
1a270 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
1a280 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  s have ever occu
1a290 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20  rred .** on the 
1a2a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a2b0 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69  ion D, then sqli
1a2c0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1a2d0 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
1a2e0 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a   .** zero..**.**
1a2f0 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e   As well as bein
1a300 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61  g set automatica
1a310 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20  lly as rows are 
1a320 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61  inserted into da
1a330 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73  tabase.** tables
1a340 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
1a350 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e  rned by this fun
1a360 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74  ction may be set
1a370 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a   explicitly by.*
1a380 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  * [sqlite3_set_l
1a390 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a3a0 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76  ()].**.** Some v
1a3b0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
1a3c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
1a3d0 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74   INSERT rows int
1a3e0 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61  o rowid tables a
1a3f0 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d  s.** part of com
1a400 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61  mitting a transa
1a410 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66  ction (e.g. to f
1a420 6c 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75  lush data accumu
1a430 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  lated in memory.
1a440 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20  ** to disk). In 
1a450 74 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71  this case subseq
1a460 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68  uent calls to th
1a470 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1a480 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20  rn the rowid.** 
1a490 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1a4a0 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49  these internal I
1a4b0 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73  NSERT operations
1a4c0 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f  , which leads to
1a4d0 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65   .** unintuitive
1a4e0 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61   results. Virtua
1a4f0 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
1a500 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20  tations that do 
1a510 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a  write to rowid.*
1a520 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73  * tables in this
1a530 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74   way can avoid t
1a540 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72  his problem by r
1a550 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69  estoring the ori
1a560 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20  ginal .** rowid 
1a570 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c  value using [sql
1a580 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1a590 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65  sert_rowid()] be
1a5a0 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a  fore returning .
1a5b0 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68  ** control to th
1a5c0 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  e user..**.** ^(
1a5d0 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
1a5e0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
1a5f0 72 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73  rigger then this
1a600 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a   routine will .*
1a610 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  * return the [ro
1a620 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
1a630 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67  rted row as long
1a640 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
1a650 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20  is .** running. 
1a660 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  Once the trigger
1a670 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74   program ends, t
1a680 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a690 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
1a6a0 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
1a6b0 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
1a6c0 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
1a6d0 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a  was fired.)^.**.
1a6e0 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
1a6f0 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
1a700 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
1a710 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
1a720 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
1a730 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
1a740 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
1a750 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a760 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
1a770 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
1a780 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
1a790 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
1a7a0 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
1a7b0 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
1a7c0 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
1a7d0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
1a7e0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1a7f0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
1a800 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
1a810 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
1a820 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
1a830 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
1a840 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
1a850 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
1a860 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
1a870 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
1a880 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
1a890 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
1a8a0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
1a8b0 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
1a8c0 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
1a8d0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
1a8e0 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
1a8f0 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
1a900 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
1a910 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
1a920 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
1a930 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
1a940 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
1a950 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
1a960 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
1a970 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
1a980 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
1a990 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
1a9a0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
1a9b0 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
1a9c0 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
1a9d0 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
1a9e0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a9f0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1aa00 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1aa10 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
1aa20 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
1aa30 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
1aa40 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1aa50 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
1aa60 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
1aa70 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
1aa80 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
1aa90 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
1aaa0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
1aab0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
1aac0 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
1aad0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
1aae0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1aaf0 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
1ab00 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
1ab10 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
1ab20 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
1ab30 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
1ab40 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
1ab50 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
1ab60 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
1ab70 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1ab80 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1ab90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1aba0 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74   the Last Insert
1abb0 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a   Rowid value..**
1abc0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1abd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1abe0 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
1abf0 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d  rt_rowid(D, R) m
1ac00 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65  ethod allows the
1ac10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
1ac20 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65  ** set the value
1ac30 20 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c   returned by cal
1ac40 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73  ling sqlite3_las
1ac50 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
1ac60 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f  ) to R .** witho
1ac70 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72  ut inserting a r
1ac80 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  ow into the data
1ac90 62 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  base..*/.void sq
1aca0 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
1acb0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
1acc0 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  te3*,sqlite3_int
1acd0 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
1ace0 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
1acf0 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
1ad00 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
1ad10 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1ad20 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1ad30 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1ad40 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
1ad50 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ied, inserted or
1ad60 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74  .** deleted by t
1ad70 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
1ad80 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
1ad90 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1ada0 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
1adb0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
1adc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
1add0 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c  ified by the onl
1ade0 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  y parameter..** 
1adf0 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
1ae00 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
1ae10 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
1ae20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76  not modify the v
1ae30 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
1ae40 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
1ae50 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63  n..**.** ^Only c
1ae60 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65  hanges made dire
1ae70 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45  ctly by the INSE
1ae80 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1ae90 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
1aea0 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
1aeb0 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61   - auxiliary cha
1aec0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
1aed0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
1aee0 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20   triggers], .** 
1aef0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
1af00 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43  ions] or [REPLAC
1af10 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
1af20 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74  solution are not
1af30 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
1af40 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   Changes to a vi
1af50 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1af60 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b  rcepted by .** [
1af70 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1af80 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20  er | INSTEAD OF 
1af90 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f  triggers] are no
1afa0 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20  t counted. ^The 
1afb0 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e  value .** return
1afc0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
1afd0 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74  anges() immediat
1afe0 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53  ely after an INS
1aff0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a  ERT, UPDATE or .
1b000 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
1b010 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65  ent run on a vie
1b020 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  w is always zero
1b030 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d  . Only changes m
1b040 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20  ade to real .** 
1b050 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74  tables are count
1b060 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73  ed..**.** Things
1b070 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69   are more compli
1b080 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c  cated if the sql
1b090 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
1b0a0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78  unction is.** ex
1b0b0 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74  ecuted while a t
1b0c0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69  rigger program i
1b0d0 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20  s running. This 
1b0e0 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68  may happen if th
1b0f0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
1b100 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  s the [changes()
1b110 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20   SQL function], 
1b120 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72  or if some other
1b130 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1b140 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71  ction invokes sq
1b150 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1b160 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74  directly. Essent
1b170 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ially:.** .** <u
1b180 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42  l>.**   <li> ^(B
1b190 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61  efore entering a
1b1a0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1b1b0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1b1c0 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
1b1d0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1b1e0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73  () function is s
1b1f0 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20  aved. After the 
1b200 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1b210 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66  .**        has f
1b220 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69  inished, the ori
1b230 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72  ginal value is r
1b240 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a  estored.)^.** .*
1b250 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69  *   <li> ^(Withi
1b260 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  n a trigger prog
1b270 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c  ram each INSERT,
1b280 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45   UPDATE and DELE
1b290 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74  TE .**        st
1b2a0 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65  atement sets the
1b2b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1b2c0 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
1b2d0 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
1b2e0 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  upon completion 
1b2f0 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f  as normal. Of co
1b300 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65  urse, this value
1b310 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64   will not includ
1b320 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79  e .**        any
1b330 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d   changes perform
1b340 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65  ed by sub-trigge
1b350 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74  rs, as the sqlit
1b360 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
1b370 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69          value wi
1b380 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20  ll be saved and 
1b390 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65  restored after e
1b3a0 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20  ach sub-trigger 
1b3b0 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f  has run.)^.** </
1b3c0 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73  ul>.** .** ^This
1b3d0 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
1b3e0 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
1b3f0 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69   function (or si
1b400 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a  milar) is used.*
1b410 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49  * by the first I
1b420 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1b430 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1b440 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1b450 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72  er, it .** retur
1b460 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20  ns the value as 
1b470 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c  set when the cal
1b480 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62  ling statement b
1b490 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a  egan executing..
1b4a0 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65  ** ^If it is use
1b4b0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
1b4c0 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75  or subsequent su
1b4d0 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ch statement wit
1b4e0 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a  hin a trigger .*
1b4f0 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76  * program, the v
1b500 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65  alue returned re
1b510 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65  flects the numbe
1b520 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
1b530 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72  ed by the .** pr
1b540 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55  evious INSERT, U
1b550 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
1b560 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1b570 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
1b580 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
1b590 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
1b5a0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
1b5b0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1b5c0 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1b5d0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1b5e0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1b5f0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1b600 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1b610 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1b620 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1b630 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b640 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1b650 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1b660 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
1b670 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
1b680 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
1b690 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
1b6a0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
1b6b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
1b6c0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
1b6d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b6e0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
1b6f0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
1b700 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1b710 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1b720 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1b730 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
1b740 66 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c  f rows inserted,
1b750 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20   modified or.** 
1b760 64 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b  deleted by all [
1b770 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
1b780 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
1b790 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74  atements complet
1b7a0 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  ed.** since the 
1b7b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b7c0 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20  ion was opened, 
1b7d0 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20  including those 
1b7e0 65 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70  executed as.** p
1b7f0 61 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70  art of trigger p
1b800 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74  rograms. ^Execut
1b810 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
1b820 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
1b830 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ent.** does not 
1b840 61 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65  affect the value
1b850 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1b860 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1b870 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68  es()..** .** ^Ch
1b880 61 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61  anges made as pa
1b890 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b  rt of [foreign k
1b8a0 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
1b8b0 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a  included in the.
1b8c0 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68  ** count, but th
1b8d0 6f 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74  ose made as part
1b8e0 20 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73   of REPLACE cons
1b8f0 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
1b900 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43  n are.** not. ^C
1b910 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
1b920 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63   that are interc
1b930 65 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44  epted by INSTEAD
1b940 20 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a   OF triggers .**
1b950 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1b960 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73  ..** .** See als
1b970 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
1b980 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
1b990 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
1b9a0 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1b9b0 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
1b9c0 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
1b9d0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1b9e0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1b9f0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1ba00 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1ba10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ba20 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1ba30 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1ba40 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1ba50 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1ba60 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
1ba70 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1ba80 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1ba90 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
1baa0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1bab0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1bac0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
1bad0 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
1bae0 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45  ning Query.** ME
1baf0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1bb00 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1bb10 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
1bb20 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
1bb30 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
1bb40 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
1bb50 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
1bb60 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
1bb70 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
1bb80 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
1bb90 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
1bba0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
1bbb0 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
1bbc0 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
1bbd0 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
1bbe0 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
1bbf0 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
1bc00 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
1bc10 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
1bc20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
1bc30 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1bc40 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
1bc50 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
1bc60 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
1bc70 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
1bc80 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
1bc90 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
1bca0 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
1bcb0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
1bcc0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
1bcd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1bce0 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
1bcf0 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
1bd00 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
1bd10 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1bd20 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
1bd30 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
1bd40 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
1bd50 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
1bd60 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
1bd70 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
1bd80 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
1bd90 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
1bda0 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
1bdb0 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
1bdc0 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
1bdd0 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
1bde0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
1bdf0 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
1be00 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
1be10 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
1be20 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
1be30 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
1be40 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
1be50 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
1be60 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
1be70 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
1be80 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
1be90 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
1bea0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
1beb0 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
1bec0 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
1bed0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
1bee0 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
1bef0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
1bf00 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
1bf10 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
1bf20 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
1bf30 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
1bf40 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
1bf50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1bf60 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
1bf70 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
1bf80 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1bf90 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1bfa0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1bfb0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1bfc0 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
1bfd0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
1bfe0 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
1bff0 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
1c000 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
1c010 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
1c020 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
1c030 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1c040 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
1c050 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1c060 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1c070 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
1c080 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
1c090 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
1c0a0 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
1c0b0 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
1c0c0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1c0d0 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
1c0e0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1c0f0 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
1c100 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
1c110 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
1c120 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
1c130 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
1c140 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
1c150 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1c160 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1c170 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1c180 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1c190 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76  ll returns..*/.v
1c1a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
1c1b0 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
1c1c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c1d0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
1c1e0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1c1f0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
1c200 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1c210 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
1c220 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
1c230 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
1c240 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
1c250 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
1c260 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
1c270 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
1c280 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
1c290 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
1c2a0 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
1c2b0 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
1c2c0 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
1c2d0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
1c2e0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
1c2f0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
1c300 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1c310 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
1c320 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
1c330 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
1c340 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
1c350 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
1c360 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
1c370 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
1c380 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
1c390 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
1c3a0 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
1c3b0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
1c3c0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
1c3d0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
1c3e0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
1c3f0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
1c400 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
1c410 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
1c420 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
1c430 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
1c440 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
1c450 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
1c460 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
1c470 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
1c480 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
1c490 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
1c4a0 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
1c4b0 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
1c4c0 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
1c4d0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
1c4e0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
1c4f0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1c500 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1c510 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
1c520 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1c530 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
1c540 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
1c550 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
1c560 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
1c570 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
1c580 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1c590 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
1c5a0 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
1c5b0 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
1c5c0 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
1c5d0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
1c5e0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
1c5f0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
1c600 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
1c610 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
1c620 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1c630 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
1c640 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
1c650 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
1c660 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
1c670 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
1c680 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
1c690 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
1c6a0 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
1c6b0 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
1c6c0 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
1c6d0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1c6e0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1c6f0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
1c700 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
1c710 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
1c720 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1c730 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
1c740 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
1c750 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1c760 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1c770 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1c780 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1c790 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
1c7a0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1c7b0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1c7c0 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
1c7d0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1c7e0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1c7f0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
1c800 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
1c810 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1c820 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
1c830 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
1c840 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
1c850 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
1c860 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1c870 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
1c880 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
1c890 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
1c8a0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73  * KEYWORDS: {bus
1c8b0 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y-handler callba
1c8c0 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65  ck} {busy handle
1c8d0 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
1c8e0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1c8f0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1c900 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75  ndler(D,X,P) rou
1c910 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
1c920 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a  back function X.
1c930 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  ** that might be
1c940 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72   invoked with ar
1c950 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65  gument P wheneve
1c960 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
1c970 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73  is made to acces
1c980 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  s a database tab
1c990 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  le associated wi
1c9a0 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  th.** [database 
1c9b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68  connection] D wh
1c9c0 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  en another threa
1c9d0 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
1c9e0 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f  has the table lo
1c9f0 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cked..** The sql
1ca00 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1ca10 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  r() interface is
1ca20 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1ca30 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nt.** [sqlite3_b
1ca40 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61  usy_timeout()] a
1ca50 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  nd [PRAGMA busy_
1ca60 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20  timeout]..**.** 
1ca70 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1ca80 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
1ca90 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
1caa0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
1cab0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
1cac0 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
1cad0 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
1cae0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
1caf0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
1cb00 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
1cb10 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
1cb20 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
1cb30 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1cb40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1cb50 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
1cb60 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
1cb70 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
1cb80 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
1cb90 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
1cba0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
1cbb0 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
1cbc0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1cbd0 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
1cbe0 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
1cbf0 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
1cc00 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
1cc10 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1cc20 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
1cc30 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20  oked previously 
1cc40 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63  for the same loc
1cc50 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
1cc60 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
1cc70 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
1cc80 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
1cc90 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
1cca0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
1ccb0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
1ccc0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
1ccd0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ] is returned.**
1cce0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1ccf0 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ion..** ^If the 
1cd00 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1cd10 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1cd20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1cd30 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  ** is made to ac
1cd40 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1cd50 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  e and the cycle 
1cd60 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1cd70 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1cd80 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1cd90 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1cda0 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1cdb0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1cdc0 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1cdd0 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1cde0 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1cdf0 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1ce00 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1ce10 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1ce20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1ce30 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1ce40 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1ce50 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74  TE_BUSY].** to t
1ce60 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1ce70 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
1ce80 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20  ng the .** busy 
1ce90 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1cea0 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1ceb0 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1cec0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1ced0 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1cee0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1cef0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1cf00 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1cf10 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1cf20 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1cf30 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1cf40 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1cf50 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1cf60 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1cf70 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1cf80 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1cf90 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1cfa0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1cfb0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1cfc0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1cfd0 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1cfe0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1cff0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1d000 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1d010 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1d020 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1d030 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1d040 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1d050 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1d060 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1d070 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1d080 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1d090 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1d0a0 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1d0b0 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1d0c0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1d0d0 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1d0e0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1d0f0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1d100 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1d110 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1d120 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1d130 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1d140 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1d150 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1d160 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1d170 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1d180 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1d190 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1d1a0 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1d1b0 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1d1c0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1d1d0 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1d1e0 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1d1f0 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1d200 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72  timeout()].** or
1d210 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41   evaluating [PRA
1d220 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1d230 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20  =N] will change 
1d240 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64  the.** busy hand
1d250 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65  ler and thus cle
1d260 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c  ar any previousl
1d270 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c  y set busy handl
1d280 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
1d290 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
1d2a0 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
1d2b0 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
1d2c0 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
1d2d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1d2e0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1d2f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
1d300 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a  In other words,.
1d310 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1d320 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ler is not reent
1d330 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20  rant.  Any such 
1d340 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c  actions.** resul
1d350 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  t in undefined b
1d360 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20  ehavior..** .** 
1d370 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d  A busy handler m
1d380 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
1d390 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1d3a0 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65  ction.** or [pre
1d3b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1d3c0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1d3d0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1d3e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1d3f0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1d400 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64  te3*,int(*)(void
1d410 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a  *,int),void*);..
1d420 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d430 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
1d440 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ut.** METHOD: sq
1d450 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1d460 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
1d470 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1d480 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
1d490 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
1d4a0 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
1d4b0 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
1d4c0 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
1d4d0 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
1d4e0 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
1d4f0 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
1d500 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
1d510 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1d520 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1d530 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
1d540 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
1d550 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
1d560 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1d570 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
1d580 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
1d590 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
1d5a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d5b0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
1d5c0 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
1d5d0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1d5e0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1d5f0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1d600 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1d610 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1d620 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1d630 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1d640 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1d650 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1d660 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1d670 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1d680 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1d690 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  t any given mome
1d6a0 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
1d6b0 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
1d6c0 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
1d6d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1d6e0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
1d6f0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
1d700 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
1d710 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
1d720 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
1d730 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
1d740 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
1d750 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
1d760 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1d770 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1d780 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1d790 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1d7a0 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1d7b0 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1d7c0 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eries.** METHOD:
1d7d0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
1d7e0 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
1d7f0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
1d800 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
1d810 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1d820 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
1d830 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1d840 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
1d850 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
1d860 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
1d870 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
1d880 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
1d890 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
1d8a0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1d8b0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
1d8c0 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
1d8d0 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
1d8e0 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
1d8f0 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
1d900 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
1d910 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
1d920 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
1d930 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
1d940 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
1d950 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
1d960 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
1d970 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
1d980 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1d990 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
1d9a0 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
1d9b0 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
1d9c0 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
1d9d0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
1d9e0 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
1d9f0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1da00 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
1da10 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
1da20 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1da30 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1da40 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
1da50 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
1da60 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
1da70 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
1da80 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
1da90 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
1daa0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1dab0 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
1dac0 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
1dad0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
1dae0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
1daf0 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
1db00 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
1db10 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
1db20 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
1db30 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
1db40 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
1db50 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
1db60 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1db70 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
1db80 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
1db90 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1dba0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1dbb0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
1dbc0 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
1dbd0 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
1dbe0 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
1dbf0 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
1dc00 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
1dc10 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
1dc20 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
1dc30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1dc40 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1dc50 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
1dc60 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
1dc70 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1dc80 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
1dc90 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
1dca0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1dcb0 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
1dcc0 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
1dcd0 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
1dce0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1dcf0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1dd00 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
1dd10 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
1dd20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1dd30 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
1dd40 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
1dd50 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
1dd60 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
1dd70 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
1dd80 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
1dd90 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1dda0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
1ddb0 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
1ddc0 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
1ddd0 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
1dde0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
1ddf0 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
1de00 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
1de10 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
1de20 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
1de30 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
1de40 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
1de50 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
1de60 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
1de70 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1de80 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1de90 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
1dea0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1deb0 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
1dec0 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
1ded0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
1dee0 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
1def0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1df00 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
1df10 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1df20 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
1df30 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1df40 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
1df50 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1df60 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
1df70 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
1df80 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
1df90 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
1dfa0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1dfb0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1dfc0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1dfd0 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
1dfe0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
1dff0 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
1e000 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
1e010 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1e020 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1e030 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1e040 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1e050 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1e060 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1e070 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1e080 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1e090 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1e0a0 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1e0b0 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1e0c0 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1e0d0 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1e0e0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1e0f0 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1e100 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1e110 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1e120 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1e130 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1e140 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1e150 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1e160 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1e170 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1e180 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1e190 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1e1a0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1e1b0 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1e1c0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1e1d0 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1e1e0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1e1f0 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1e200 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1e210 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1e220 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1e230 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1e240 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1e250 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1e260 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1e270 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1e280 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1e290 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1e2a0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1e2b0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1e2c0 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1e2d0 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1e2e0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1e2f0 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1e300 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1e310 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1e320 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1e330 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1e340 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1e350 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1e360 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1e370 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1e380 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1e390 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1e3a0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1e3b0 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1e3c0 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1e3d0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1e3e0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1e3f0 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1e400 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1e410 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
1e420 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
1e430 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1e440 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
1e450 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
1e460 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1e470 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
1e480 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
1e490 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
1e4a0 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
1e4b0 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
1e4c0 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
1e4d0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1e4e0 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
1e4f0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1e500 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
1e510 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1e520 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
1e530 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1e540 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
1e550 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
1e560 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
1e570 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
1e580 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1e590 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
1e5a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e5b0 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
1e5c0 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
1e5d0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1e5e0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1e5f0 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
1e600 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
1e610 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
1e620 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
1e630 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1e640 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
1e650 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d  nes understand m
1e660 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f  ost of the commo
1e670 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67  n K&R formatting
1e680 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75   options,.** plu
1e690 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  s some additiona
1e6a0 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66  l non-standard f
1e6b0 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64  ormats, detailed
1e6c0 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20   below..** Note 
1e6d0 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65  that some of the
1e6e0 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f   more obscure fo
1e6f0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1e700 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20   from recent.** 
1e710 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61  C-library standa
1e720 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20  rds are omitted 
1e730 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d  from this implem
1e740 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  entation..**.** 
1e750 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1e760 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1e770 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1e780 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1e790 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1e7a0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1e7b0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1e7c0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1e7d0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1e7e0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1e7f0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1e800 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1e810 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1e820 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1e830 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1e840 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1e850 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1e860 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1e870 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1e880 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1e890 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1e8a0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1e8b0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1e8c0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1e8d0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1e8e0 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1e8f0 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1e900 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1e910 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1e920 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1e930 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1e940 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1e950 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1e960 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1e970 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1e980 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1e990 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1e9a0 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1e9b0 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1e9c0 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1e9d0 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1e9e0 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1e9f0 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1ea00 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1ea10 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1ea20 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1ea30 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1ea40 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1ea50 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1ea60 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1ea70 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1ea80 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1ea90 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1eaa0 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1eab0 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1eac0 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1ead0 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1eae0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1eaf0 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1eb00 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1eb10 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1eb20 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1eb30 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1eb40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1eb50 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1eb60 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1eb70 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1eb80 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1eb90 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1eba0 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1ebb0 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1ebc0 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1ebd0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1ebe0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1ebf0 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1ec00 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1ec10 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1ec20 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1ec30 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1ec40 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1ec50 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1ec60 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1ec70 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1ec80 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1ec90 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1eca0 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1ecb0 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1ecc0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1ecd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1ece0 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1ecf0 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1ed00 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1ed10 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1ed20 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1ed30 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1ed40 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1ed50 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1ed60 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1ed70 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1ed80 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1ed90 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1eda0 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1edb0 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1edc0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1edd0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1ede0 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1edf0 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20  %q", "%Q", "%w" 
1ee00 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1ee10 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1ee20 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1ee30 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1ee40 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1ee50 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1ee60 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1ee70 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1ee80 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1ee90 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1eea0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1eeb0 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1eec0 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1eed0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1eee0 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1eef0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1ef00 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1ef10 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1ef20 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1ef30 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1ef40 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1ef50 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1ef60 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1ef70 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1ef80 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1ef90 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1efa0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1efb0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1efc0 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1efd0 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1efe0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1eff0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1f000 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1f010 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1f020 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1f030 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1f040 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1f050 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1f060 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1f070 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1f080 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1f090 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1f0a0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1f0b0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1f0c0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1f0d0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1f0e0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1f0f0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1f100 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1f110 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1f120 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1f130 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1f140 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1f150 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1f160 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1f170 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1f180 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1f190 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1f1a0 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1f1b0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1f1c0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1f1d0 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1f1e0 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1f1f0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1f200 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1f210 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1f220 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1f230 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1f240 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1f250 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1f260 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1f270 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1f280 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1f290 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1f2a0 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1f2b0 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1f2c0 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1f2d0 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1f2e0 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1f2f0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1f300 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1f310 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1f320 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1f330 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1f340 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1f350 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1f360 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1f370 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1f380 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1f390 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1f3a0 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1f3b0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1f3c0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1f3d0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1f3e0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1f3f0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1f400 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1f410 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1f420 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1f430 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1f440 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1f450 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1f460 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1f470 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1f480 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1f490 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1f4a0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1f4b0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1f4c0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1f4d0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1f4e0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1f4f0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1f500 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1f510 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1f520 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1f530 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1f540 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1f550 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1f560 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1f570 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1f580 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1f590 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b  ng option is lik
1f5a0 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68  e "%q" except th
1f5b0 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f  at it expects to
1f5c0 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  .** be contained
1f5d0 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71   within double-q
1f5e0 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66  uotes instead of
1f5f0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20   single quotes, 
1f600 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65  and it.** escape
1f610 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f  s the double-quo
1f620 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73  te character ins
1f630 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67  tead of the sing
1f640 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72  le-quote.** char
1f650 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25  acter.)^  The "%
1f660 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
1f670 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64  tion is intended
1f680 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65   for safely inse
1f690 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61  rting.** table a
1f6a0 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  nd column names 
1f6b0 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74  into a construct
1f6c0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1f6d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1f6e0 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1f6f0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1f700 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1f710 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1f720 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1f730 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1f740 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1f750 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1f760 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f770 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1f780 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1f790 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69  )^.*/.char *sqli
1f7a0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1f7b0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68  t char*,...);.ch
1f7c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72  ar *sqlite3_vmpr
1f7d0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1f7e0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72  , va_list);.char
1f7f0 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   *sqlite3_snprin
1f800 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1f810 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a  st char*, ...);.
1f820 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73  char *sqlite3_vs
1f830 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1f840 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  *,const char*, v
1f850 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  a_list);../*.** 
1f860 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1f870 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73   Allocation Subs
1f880 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ystem.**.** The 
1f890 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
1f8a0 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
1f8b0 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
1f8c0 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
1f8d0 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
1f8e0 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
1f8f0 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
1f900 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
1f910 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
1f920 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
1f930 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
1f940 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
1f950 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
1f960 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
1f970 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1f980 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
1f990 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  rations..**.** ^
1f9a0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1f9b0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  oc() routine ret
1f9c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1f9d0 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20  o a block.** of 
1f9e0 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20  memory at least 
1f9f0 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74  N bytes in lengt
1fa00 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  h, where N is th
1fa10 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  e parameter..** 
1fa20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
1fa30 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74  oc() is unable t
1fa40 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69  o obtain suffici
1fa50 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f  ent free.** memo
1fa60 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61  ry, it returns a
1fa70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1fa80 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65  ^If the paramete
1fa90 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  r N to.** sqlite
1faa0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  3_malloc() is ze
1fab0 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  ro or negative t
1fac0 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  hen sqlite3_mall
1fad0 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  oc() returns.** 
1fae0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1faf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1fb00 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72  e3_malloc64(N) r
1fb10 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73  outine works jus
1fb20 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  t like.** sqlite
1fb30 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65  3_malloc(N) exce
1fb40 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20  pt that N is an 
1fb50 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20  unsigned 64-bit 
1fb60 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
1fb70 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33  ** of a signed 3
1fb80 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a  2-bit integer..*
1fb90 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
1fba0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
1fbb0 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
1fbc0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
1fbd0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
1fbe0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1fbf0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
1fc00 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
1fc10 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
1fc20 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
1fc30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
1fc40 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
1fc50 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
1fc60 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1fc70 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
1fc80 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
1fc90 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
1fca0 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
1fcb0 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
1fcc0 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
1fcd0 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
1fce0 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
1fcf0 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
1fd00 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
1fd10 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
1fd20 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
1fd30 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
1fd40 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
1fd50 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
1fd60 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
1fd70 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
1fd80 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
1fd90 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
1fda0 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
1fdb0 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
1fdc0 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
1fdd0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
1fde0 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
1fdf0 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
1fe00 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1fe10 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1fe20 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
1fe30 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1fe40 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  loc(X,N) interfa
1fe50 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
1fe60 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
1fe70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1fe80 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65  on X to be at le
1fe90 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20  ast N bytes..** 
1fea0 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65  ^If the X parame
1feb0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1fec0 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69  ealloc(X,N).** i
1fed0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1fee0 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
1fef0 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
1ff00 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
1ff10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e  lite3_malloc(N).
1ff20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61  .** ^If the N pa
1ff30 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1ff40 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1ff50 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
1ff60 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
1ff70 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
1ff80 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
1ff90 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1ffa0 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e  e3_free(X)..** ^
1ffb0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ffc0 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70  X,N) returns a p
1ffd0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
1ffe0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
1fff0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
20000 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
20010 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
20020 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61  ient memory is a
20030 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
20040 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
20050 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
20060 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
20070 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
20080 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
20090 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
200a0 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
200b0 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
200c0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
200d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
200e0 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72  N) and the prior
200f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66   allocation is f
20100 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  reed..** ^If sql
20110 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
20120 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
20130 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  nd N is positive
20140 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72  , then the.** pr
20150 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
20160 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
20170 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20180 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69  realloc64(X,N) i
20190 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20  nterfaces works 
201a0 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
201b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
201c0 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  ,N) except that 
201d0 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e  N is a 64-bit un
201e0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69  signed integer i
201f0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33  nstead.** of a 3
20200 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
20210 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  eger..**.** ^If 
20220 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c  X is a memory al
20230 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75  location previou
20240 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
20250 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
20260 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
20270 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74  alloc64(), sqlit
20280 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72  e3_realloc(), or
20290 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
202a0 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  64(), then.** sq
202b0 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72  lite3_msize(X) r
202c0 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20  eturns the size 
202d0 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61  of that memory a
202e0 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74  llocation in byt
202f0 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  es..** ^The valu
20300 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
20310 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d  lite3_msize(X) m
20320 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74  ight be larger t
20330 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a  han the number.*
20340 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65  * of bytes reque
20350 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20  sted when X was 
20360 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20  allocated.  ^If 
20370 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  X is a NULL poin
20380 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ter then.** sqli
20390 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
203a0 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58  urns zero.  If X
203b0 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74   points to somet
203c0 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74  hing that is not
203d0 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  .** the beginnin
203e0 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  g of memory allo
203f0 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74  cation, or if it
20400 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72   points to a for
20410 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d  merly.** valid m
20420 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
20430 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65   that has now be
20440 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74  en freed, then t
20450 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
20460 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  f sqlite3_msize(
20470 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  X) is undefined 
20480 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72  and possibly har
20490 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mful..**.** ^The
204a0 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
204b0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
204c0 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  oc(), sqlite3_re
204d0 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
204e0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
204f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
20500 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c  loc64().** is al
20510 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
20520 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
20530 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
20540 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
20550 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
20560 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
20570 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
20580 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
20590 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
205a0 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
205b0 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
205c0 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
205d0 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
205e0 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
205f0 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
20600 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
20610 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
20620 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
20630 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
20640 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
20650 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
20660 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
20670 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
20680 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
20690 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
206a0 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
206b0 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
206c0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
206d0 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
206e0 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
206f0 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
20700 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
20710 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
20720 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
20730 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
20740 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
20750 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
20760 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
20770 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
20780 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
20790 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
207a0 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
207b0 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
207c0 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
207d0 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
207e0 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
207f0 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
20800 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
20810 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
20820 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
20830 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
20840 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
20850 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
20860 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
20870 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
20880 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
20890 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
208a0 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
208b0 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
208c0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
208d0 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
208e0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
208f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
20900 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20910 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
20920 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
20930 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
20940 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
20950 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
20960 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
20970 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
20980 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
20990 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
209a0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
209b0 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
209c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
209d0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
209e0 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a  e3_malloc(int);.
209f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
20a00 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75  lloc64(sqlite3_u
20a10 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71  int64);.void *sq
20a20 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
20a30 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
20a40 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
20a50 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
20a60 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  3_uint64);.void 
20a70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
20a80 64 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e  d*);.sqlite3_uin
20a90 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  t64 sqlite3_msiz
20aa0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
20ab0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
20ac0 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
20ad0 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
20ae0 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
20af0 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
20b00 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
20b10 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
20b20 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
20b30 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
20b40 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
20b50 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
20b60 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
20b70 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
20b80 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
20b90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
20ba0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
20bb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
20bc0 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
20bd0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
20be0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
20bf0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
20c00 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
20c10 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
20c20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
20c30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
20c40 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
20c50 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
20c60 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
20c70 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
20c80 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
20c90 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
20ca0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
20cb0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
20cc0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
20cd0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
20ce0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
20cf0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
20d00 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
20d10 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
20d20 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
20d30 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
20d40 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
20d50 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
20d60 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
20d70 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
20d80 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
20d90 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
20da0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
20db0 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
20dc0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
20dd0 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
20de0 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
20df0 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
20e00 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
20e10 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
20e20 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
20e30 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
20e40 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
20e50 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
20e60 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
20e70 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
20e80 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
20e90 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
20ea0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
20eb0 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
20ec0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
20ed0 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
20ee0 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
20ef0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
20f00 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
20f10 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
20f20 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20f30 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
20f40 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
20f50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
20f60 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
20f70 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
20f80 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
20f90 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
20fa0 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
20fb0 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
20fc0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
20fd0 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
20fe0 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
20ff0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
21000 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
21010 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
21020 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
21030 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
21040 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
21050 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
21060 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
21070 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
21080 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
21090 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
210a0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
210b0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
210c0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
210d0 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
210e0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
210f0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
21100 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
21110 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
21120 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
21130 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50  fer P..** ^The P
21140 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62   parameter can b
21150 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
21160 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
21170 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
21180 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
21190 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
211a0 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
211b0 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
211c0 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c  an one or a NULL
211d0 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20   pointer for P, 
211e0 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73  then the PRNG is
211f0 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67  .** seeded using
21200 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
21210 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52  ined from the xR
21220 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
21230 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   of.** the defau
21240 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
21250 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20   object..** ^If 
21260 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
21270 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
21280 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20  e had an N of 1 
21290 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a  or more and a.**
212a0 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e   non-NULL P then
212b0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
212c0 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
212d0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
212e0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
212f0 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
21300 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
21310 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
21320 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
21330 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
21340 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
21350 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21360 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
21370 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
21380 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
21390 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f  sqlite3.** KEYWO
213a0 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72  RDS: {authorizer
213b0 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a   callback}.**.**
213c0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
213d0 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
213e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
213f0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
21400 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
21410 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
21420 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
21430 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
21440 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
21450 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
21460 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
21470 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
21480 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
21490 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
214a0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
214b0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
214c0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
214d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
214e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
214f0 65 70 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c  epare16()], [sql
21500 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
21510 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71  2()],.** and [sq
21520 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
21530 76 33 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v3()].  ^At vari
21540 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
21550 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
21560 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
21570 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
21580 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
21590 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
215a0 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
215b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
215c0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
215d0 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
215e0 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
215f0 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
21600 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
21610 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
21620 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
21630 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
21640 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
21650 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
21660 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
21670 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
21680 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
21690 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
216a0 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
216b0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
216c0 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
216d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
216e0 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
216f0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
21700 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
21710 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
21720 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
21730 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
21740 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
21750 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
21760 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
21770 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
21780 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
21790 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
217a0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
217b0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
217c0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
217d0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
217e0 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
217f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
21800 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
21810 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
21820 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
21830 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
21840 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
21850 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
21860 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
21870 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21880 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
21890 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
218a0 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
218b0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
218c0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
218d0 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
218e0 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
218f0 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
21900 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
21910 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
21920 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21930 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
21940 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
21950 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
21960 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
21970 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
21980 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
21990 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
219a0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
219b0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
219c0 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
219d0 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
219e0 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
219f0 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
21a00 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
21a10 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
21a20 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
21a30 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
21a40 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69   callback are ei
21a50 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ther NULL pointe
21a60 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69  rs or zero-termi
21a70 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a  nated strings.**
21a80 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
21a90 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73  ditional details
21aa0 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
21ab0 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
21ac0 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  ed..** Applicati
21ad0 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20  ons must always 
21ae0 62 65 20 70 72 65 70 61 72 65 64 20 74 6f 20 65  be prepared to e
21af0 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20  ncounter a NULL 
21b00 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a  pointer in any.*
21b10 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 74  * of the third t
21b20 68 72 6f 75 67 68 20 74 68 65 20 73 69 78 74 68  hrough the sixth
21b30 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
21b40 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
21b50 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
21b60 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
21b70 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
21b80 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
21b90 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
21ba0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
21bb0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
21bc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21bd0 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
21be0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
21bf0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
21c00 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
21c10 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
21c20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
21c30 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
21c40 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
21c50 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
21c60 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
21c70 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
21c80 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
21c90 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
21ca0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
21cb0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
21cc0 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
21cd0 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20  table..** ^When 
21ce0 61 20 74 61 62 6c 65 20 69 73 20 72 65 66 65 72  a table is refer
21cf0 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45  enced by a [SELE
21d00 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d  CT] but no colum
21d10 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20  n values are.** 
21d20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74  extracted from t
21d30 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65  hat table (for e
21d40 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72  xample in a quer
21d50 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43  y like.** "SELEC
21d60 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20  T count(*) FROM 
21d70 74 61 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b  tab") then the [
21d80 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74  SQLITE_READ] aut
21d90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21da0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  .** is invoked o
21db0 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74 61 62  nce for that tab
21dc0 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e  le with a column
21dd0 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e   name that is an
21de0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
21df0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
21e00 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
21e10 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
21e20 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
21e30 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
21e40 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
21e50 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
21e60 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
21e70 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
21e80 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
21e90 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
21ea0 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
21eb0 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
21ec0 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
21ed0 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
21ee0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21ef0 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
21f00 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
21f10 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
21f20 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
21f30 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
21f40 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
21f50 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
21f60 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
21f70 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
21f80 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
21f90 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
21fa0 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
21fb0 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
21fc0 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
21fd0 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
21fe0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
21ff0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
22000 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
22010 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
22020 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
22030 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
22040 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
22050 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
22060 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
22070 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
22080 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
22090 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
220a0 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
220b0 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
220c0 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
220d0 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
220e0 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
220f0 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
22100 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
22110 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
22120 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
22130 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
22140 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
22150 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
22160 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
22170 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
22180 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
22190 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
221a0 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
221b0 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
221c0 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
221d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
221e0 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
221f0 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
22200 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
22210 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
22220 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
22230 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
22240 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
22250 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
22260 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
22270 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
22280 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
22290 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
222a0 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
222b0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
222c0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
222d0 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
222e0 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
222f0 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
22300 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
22310 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
22320 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
22330 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
22340 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
22350 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
22360 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
22370 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
22380 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
22390 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
223a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
223b0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
223c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
223d0 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
223e0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
223f0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
22400 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
22410 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
22420 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
22430 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
22440 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
22450 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
22460 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
22470 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
22480 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
22490 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
224a0 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
224b0 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
224c0 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
224d0 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
224e0 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
224f0 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
22500 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
22510 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
22520 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
22530 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
22540 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22550 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
22560 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
22570 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
22580 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
22590 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
225a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
225b0 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
225c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
225d0 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
225e0 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
225f0 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
22600 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
22610 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
22620 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
22630 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
22640 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
22650 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
22660 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
22670 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
22680 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
22690 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
226a0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
226b0 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
226c0 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e  ma change..*/.in
226d0 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
226e0 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
226f0 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
22700 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
22710 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
22720 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
22730 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
22740 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
22750 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
22760 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
22770 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
22780 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
22790 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
227a0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
227b0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
227c0 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
227d0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
227e0 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
227f0 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
22800 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
22810 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
22820 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
22830 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
22840 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
22850 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
22860 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
22870 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
22880 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
22890 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
228a0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
228b0 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
228c0 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
228d0 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72  as a [conflict r
228e0 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a  esolution mode].
228f0 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ** returned from
22900 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74   the [sqlite3_vt
22910 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
22920 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
22930 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22940 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
22950 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
22960 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
22970 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
22980 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
22990 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
229a0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
229b0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
229c0 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
229d0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
229e0 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
229f0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
22a00 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
22a10 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
22a20 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
22a30 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
22a40 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
22a50 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
22a60 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
22a70 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
22a80 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
22a90 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
22aa0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
22ab0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
22ac0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
22ad0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
22ae0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
22af0 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
22b00 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
22b10 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
22b20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
22b30 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
22b40 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
22b50 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
22b60 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
22b70 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
22b80 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
22b90 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
22ba0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
22bb0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
22bc0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
22bd0 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
22be0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
22bf0 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
22c00 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
22c10 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
22c20 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
22c30 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65  arameter.  ^(The
22c40 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
22c50 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  o the.** authori
22c60 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
22c70 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
22c80 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22  database ("main"
22c90 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63  , "temp",.** etc
22ca0 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65  .) if applicable
22cb0 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61  .)^  ^The 6th pa
22cc0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
22cd0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22ce0 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d  ck.** is the nam
22cf0 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d  e of the inner-m
22d00 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76  ost trigger or v
22d10 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70  iew that is resp
22d20 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74  onsible for.** t
22d30 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  he access attemp
22d40 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69  t or NULL if thi
22d50 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74  s access attempt
22d60 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f   is directly fro
22d70 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53  m.** top-level S
22d80 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a  QL code..*/./***
22d90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22da0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22db0 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a  ******** 3rd ***
22dc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a  ********* 4th **
22dd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69  *********/.#defi
22de0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22df0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
22e00 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  1   /* Index Nam
22e10 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
22e20 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22e30 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22e40 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
22e50 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22e60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22e70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22e80 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
22e90 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20  EMP_INDEX     3 
22ea0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
22eb0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
22ec0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22ed0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
22ee0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20  MP_TABLE     4  
22ef0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22f00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22f10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22f20 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
22f30 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20  P_TRIGGER   5   
22f40 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
22f50 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22f60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22f70 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
22f80 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f  _VIEW      6   /
22f90 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
22fa0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22fb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22fc0 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47  ITE_CREATE_TRIGG
22fd0 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  ER        7   /*
22fe0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
22ff0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23000 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23010 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20  TE_CREATE_VIEW  
23020 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20           8   /* 
23030 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
23040 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23050 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23060 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  E_DELETE        
23070 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54          9   /* T
23080 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
23090 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
230a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
230b0 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20  _DROP_INDEX     
230c0 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e        10   /* In
230d0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
230e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
230f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23100 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20  DROP_TABLE      
23110 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62       11   /* Tab
23120 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
23130 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23140 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
23150 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ROP_TEMP_INDEX  
23160 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65      12   /* Inde
23170 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
23180 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
23190 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
231a0 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  OP_TEMP_TABLE   
231b0 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65     13   /* Table
231c0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
231d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
231e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
231f0 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  P_TEMP_TRIGGER  
23200 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65    14   /* Trigge
23210 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
23220 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
23230 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
23240 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
23250 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   15   /* View Na
23260 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
23270 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
23280 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
23290 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20  TRIGGER         
232a0 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  16   /* Trigger 
232b0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
232c0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
232d0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
232e0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31  IEW            1
232f0 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  7   /* View Name
23300 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
23310 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23320 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20  e SQLITE_INSERT 
23330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
23340 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
23350 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23360 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23370 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20   SQLITE_PRAGMA  
23380 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20               19 
23390 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65    /* Pragma Name
233a0 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20       1st arg or 
233b0 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  NULL */.#define 
233c0 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20  SQLITE_READ     
233d0 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20              20  
233e0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
233f0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
23400 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23410 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20  QLITE_SELECT    
23420 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20             21   
23430 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
23440 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
23450 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23460 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e  LITE_TRANSACTION
23470 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f            22   /
23480 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
23490 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
234a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
234b0 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20  ITE_UPDATE      
234c0 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a           23   /*
234d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
234e0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
234f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23500 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20  TE_ATTACH       
23510 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20          24   /* 
23520 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20  Filename        
23530 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23540 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23550 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20  E_DETACH        
23560 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44         25   /* D
23570 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e  atabase Name   N
23580 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23590 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
235a0 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20  _ALTER_TABLE    
235b0 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61        26   /* Da
235c0 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61  tabase Name   Ta
235d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
235e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
235f0 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  REINDEX         
23600 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64       27   /* Ind
23610 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  ex Name      NUL
23620 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23630 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
23640 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20  NALYZE          
23650 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c      28   /* Tabl
23660 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
23670 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23680 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
23690 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20  EATE_VTABLE     
236a0 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65     29   /* Table
236b0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
236c0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
236d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
236e0 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  P_VTABLE        
236f0 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    30   /* Table 
23700 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65  Name      Module
23710 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
23720 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43  fine SQLITE_FUNC
23730 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20  TION            
23740 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   31   /* NULL   
23750 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f           Functio
23760 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66  n Name   */.#def
23770 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50  ine SQLITE_SAVEP
23780 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  OINT            
23790 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  32   /* Operatio
237a0 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e  n       Savepoin
237b0 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69  t Name  */.#defi
237c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20  ne SQLITE_COPY  
237d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
237e0 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72  0   /* No longer
237f0 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65   used */.#define
23800 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56   SQLITE_RECURSIV
23810 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20  E            33 
23820 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
23830 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
23840 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43       */../*.** C
23850 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67  API3REF: Tracing
23860 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46   And Profiling F
23870 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
23880 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
23890 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
238a0 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e   are deprecated.
238b0 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   Use the [sqlite
238c0 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e  3_trace_v2()] in
238d0 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65  terface.** inste
238e0 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e  ad of the routin
238f0 65 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72  es described her
23900 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
23910 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
23920 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
23930 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
23940 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
23950 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
23960 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
23970 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
23980 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
23990 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
239a0 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
239b0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
239c0 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
239d0 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
239e0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
239f0 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
23a00 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
23a10 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
23a20 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
23a30 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
23a40 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
23a50 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
23a60 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
23a70 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
23a80 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
23a90 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
23aa0 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
23ab0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
23ac0 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
23ad0 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
23ae0 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
23af0 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
23b00 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
23b10 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
23b20 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
23b30 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
23b40 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
23b50 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
23b60 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
23b70 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
23b80 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
23b90 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
23ba0 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
23bb0 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
23bc0 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
23bd0 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
23be0 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
23bf0 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
23c00 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
23c10 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
23c20 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
23c30 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
23c40 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
23c50 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
23c60 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
23c70 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
23c80 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
23c90 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
23ca0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
23cb0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
23cc0 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
23cd0 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
23ce0 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
23cf0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
23d00 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
23d10 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
23d20 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
23d30 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
23d40 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
23d50 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
23d60 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
23d70 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
23d80 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
23d90 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
23da0 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
23db0 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
23dc0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
23dd0 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
23de0 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
23df0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
23e00 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
23e10 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
23e20 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
23e30 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
23e40 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
23e50 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
23e60 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
23e70 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
23e80 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
23e90 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
23ea0 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
23eb0 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
23ec0 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65  .   void(*xTrace
23ed0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
23ee0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
23ef0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
23f00 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
23f10 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
23f20 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
23f30 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
23f40 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
23f50 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
23f60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
23f70 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43  QL Trace Event C
23f80 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
23f90 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a  : SQLITE_TRACE.*
23fa0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
23fb0 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c  ants identify cl
23fc0 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20  asses of events 
23fd0 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69  that can be moni
23fe0 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74  tored.** using t
23ff0 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
24000 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20  e_v2()] tracing 
24010 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69 72  logic.  The thir
24020 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
24030 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
24040 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65  v2()] is an OR-e
24050 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
24060 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a   one or more of.
24070 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
24080 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68   constants.  ^Th
24090 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
240a0 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
240b0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65  llback.** is one
240c0 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
240d0 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  g constants..**.
240e0 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63  ** New tracing c
240f0 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
24100 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
24110 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
24120 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
24130 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d  k has four argum
24140 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28  ents: xCallback(
24150 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68  T,C,P,X)..** ^Th
24160 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e T argument is 
24170 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67  one of the integ
24180 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 62  er type codes ab
24190 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ove..** ^The C a
241a0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
241b0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
241c0 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
241d0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  in as the.** fou
241e0 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
241f0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
24200 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61  2()]..** The P a
24210 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61  nd X arguments a
24220 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73  re pointers whos
24230 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e  e meanings depen
24240 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64  d on T..**.** <d
24250 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  l>.** [[SQLITE_T
24260 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e  RACE_STMT]] <dt>
24270 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
24280 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  T</dt>.** <dd>^A
24290 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  n SQLITE_TRACE_S
242a0 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  TMT callback is 
242b0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70  invoked when a p
242c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
242d0 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e  t.** first begin
242e0 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f  s running and po
242f0 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20  ssibly at other 
24300 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65  times during the
24310 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  .** execution of
24320 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
24330 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73  atement, such as
24340 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66   at the start of
24350 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72   each.** trigger
24360 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68   subprogram. ^Th
24370 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
24380 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
24390 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
243a0 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58  atement]. ^The X
243b0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
243c0 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
243d0 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  ng which.** is t
243e0 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51  he unexpanded SQ
243f0 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 72  L text of the pr
24400 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24410 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
24420 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  nt .** that indi
24430 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61  cates the invoca
24440 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65  tion of a trigge
24450 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  r.  ^The callbac
24460 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a  k can compute.**
24470 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 74   the same text t
24480 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62  hat would have b
24490 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  een returned by 
244a0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
244b0 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20  te3_trace()].** 
244c0 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 69  interface by usi
244d0 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  ng the X argumen
244e0 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20  t when X begins 
244f0 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e  with "--" and in
24500 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  voking.** [sqlit
24510 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
24520 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  P)] otherwise..*
24530 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
24540 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64  ACE_PROFILE]] <d
24550 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  t>SQLITE_TRACE_P
24560 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ROFILE</dt>.** <
24570 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
24580 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
24590 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70  back provides ap
245a0 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20  proximately the 
245b0 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  same.** informat
245c0 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64  ion as is provid
245d0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
245e0 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61  e3_profile()] ca
245f0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
24600 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
24610 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
24620 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24630 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
24640 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
24650 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74   to a 64-bit int
24660 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68  eger which is th
24670 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a  e estimated of.*
24680 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
24690 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20  nanosecond that 
246a0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
246b0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
246c0 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  un..** ^The SQLI
246d0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
246e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
246f0 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 74  oked when the st
24700 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
24710 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
24720 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74  _TRACE_ROW]] <dt
24730 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f  >SQLITE_TRACE_RO
24740 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  W</dt>.** <dd>^A
24750 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  n SQLITE_TRACE_R
24760 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  OW callback is i
24770 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
24780 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
24790 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65  atement generate
247a0 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  s a single row o
247b0 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e  f result.  .** ^
247c0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
247d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
247e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
247f0 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
24800 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  ** X argument is
24810 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   unused..**.** [
24820 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c  [SQLITE_TRACE_CL
24830 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  OSE]] <dt>SQLITE
24840 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74  _TRACE_CLOSE</dt
24850 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
24860 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
24870 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
24880 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62  ked when a datab
24890 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
248a0 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68  n closes..** ^Th
248b0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
248c0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
248d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
248e0 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a  ction] object.**
248f0 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d   and the X argum
24900 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
24910 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
24920 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
24930 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a  STMT       0x01.
24940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
24950 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20  RACE_PROFILE    
24960 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x02.#define SQL
24970 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20  ITE_TRACE_ROW   
24980 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e       0x04.#defin
24990 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  e SQLITE_TRACE_C
249a0 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a  LOSE      0x08..
249b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
249c0 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a  SQL Trace Hook.*
249d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
249e0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
249f0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c  ite3_trace_v2(D,
24a00 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  M,X,P) interface
24a10 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72 61   registers a tra
24a20 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  ce callback.** f
24a30 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73  unction X agains
24a40 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  t [database conn
24a50 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67  ection] D, using
24a60 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d   property mask M
24a70 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20  .** and context 
24a80 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20  pointer P.  ^If 
24a90 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  the X callback i
24aa0 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20  s.** NULL or if 
24ab0 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65  the M mask is ze
24ac0 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67  ro, then tracing
24ad0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54   is disabled.  T
24ae0 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74  he.** M argument
24af0 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62   should be the b
24b00 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d  itwise OR-ed com
24b10 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a  bination of.** z
24b20 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c  ero or more [SQL
24b30 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74  ITE_TRACE] const
24b40 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  ants..**.** ^Eac
24b50 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  h call to either
24b60 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
24b70 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63   or sqlite3_trac
24b80 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 73  e_v2() overrides
24b90 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61   .** (cancels) a
24ba0 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74  ny prior calls t
24bb0 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  o sqlite3_trace(
24bc0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
24bd0 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  ce_v2()..**.** ^
24be0 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  The X callback i
24bf0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
24c00 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76  er any of the ev
24c10 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 20  ents identified 
24c20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63  by .** mask M oc
24c30 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67  cur.  ^The integ
24c40 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  er return value 
24c50 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63  from the callbac
24c60 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a  k is currently.*
24c70 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67  * ignored, thoug
24c80 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67  h this may chang
24c90 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  e in future rele
24ca0 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a  ases.  Callback.
24cb0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
24cc0 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ns should return
24cd0 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20   zero to ensure 
24ce0 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69  future compatibi
24cf0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  lity..**.** ^A t
24d00 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
24d10 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f   invoked with fo
24d20 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61  ur arguments: ca
24d30 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e  llback(T,C,P,X).
24d40 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d  .** ^The T argum
24d50 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ent is one of th
24d60 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
24d70 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f  .** constants to
24d80 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 68   indicate why th
24d90 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69  e callback was i
24da0 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nvoked..** ^The 
24db0 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
24dc0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
24dd0 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ext pointer..** 
24de0 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75  The P and X argu
24df0 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65  ments are pointe
24e00 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67  rs whose meaning
24e10 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a  s depend on T..*
24e20 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
24e30 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65  _trace_v2() inte
24e40 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65  rface is intende
24e50 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65  d to replace the
24e60 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
24e70 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74  faces [sqlite3_t
24e80 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  race()] and [sql
24e90 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c  ite3_profile()],
24ea0 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a   both of which.*
24eb0 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64  * are deprecated
24ec0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
24ed0 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c  _trace_v2(.  sql
24ee0 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65  ite3*,.  unsigne
24ef0 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a  d uMask,.  int(*
24f00 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67  xCallback)(unsig
24f10 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c  ned,void*,void*,
24f20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  void*),.  void *
24f30 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pCtx.);../*.** C
24f40 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
24f50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
24f60 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
24f70 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
24f80 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
24f90 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50  _handler(D,N,X,P
24fa0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
24fb0 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a  es the callback.
24fc0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f  ** function X to
24fd0 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69   be invoked peri
24fe0 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20  odically during 
24ff0 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c  long running cal
25000 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
25010 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69  3_exec()], [sqli
25020 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20  te3_step()] and 
25030 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
25040 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74  le()] for.** dat
25050 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25060 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20   D.  An example 
25070 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20  use for this.** 
25080 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20  interface is to 
25090 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74  keep a GUI updat
250a0 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67  ed during a larg
250b0 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  e query..**.** ^
250c0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20  The parameter P 
250d0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
250e0 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  h as the only pa
250f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a  rameter to the .
25100 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
25110 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61  tion X.  ^The pa
25120 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65  rameter N is the
25130 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d   approximate num
25140 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
25150 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
25160 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
25170 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
25180 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
25190 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
251a0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
251b0 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73  .  ^If N is less
251c0 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74   than one then t
251d0 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68  he progress.** h
251e0 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c  andler is disabl
251f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20  ed..**.** ^Only 
25200 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
25210 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
25220 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
25230 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
25240 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25250 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
25260 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
25270 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
25280 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
25290 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
252a0 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
252b0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
252c0 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
252d0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
252e0 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
252f0 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
25300 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
25310 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
25320 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
25330 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
25340 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
25350 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
25360 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
25370 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
25380 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
25390 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
253a0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
253b0 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
253c0 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
253d0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
253e0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
253f0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
25400 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
25410 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
25420 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
25430 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
25440 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
25450 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
25460 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
25470 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
25480 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
25490 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
254a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
254b0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
254c0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
254d0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
254e0 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
254f0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
25500 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
25510 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
25520 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
25530 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
25540 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
25550 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e Connection.** 
25560 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c  CONSTRUCTOR: sql
25570 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
25580 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
25590 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
255a0 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
255b0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
255c0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
255d0 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
255e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
255f0 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
25600 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
25610 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
25620 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
25630 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
25640 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
25650 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
25660 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
25670 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
25680 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
25690 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
256a0 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
256b0 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
256c0 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
256d0 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
256e0 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
256f0 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
25700 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
25710 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
25720 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
25730 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
25740 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
25750 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
25760 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
25770 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
25780 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
25790 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
257a0 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
257b0 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
257c0 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
257d0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
257e0 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
257f0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
25800 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
25810 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
25820 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
25830 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
25840 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
25850 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
25860 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
25870 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
25880 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
25890 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
258a0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
258b0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
258c0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
258d0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
258e0 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55  coding will be U
258f0 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73  TF-8 for databas
25900 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
25910 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
25920 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
25930 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64  en_v2().  ^The d
25940 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
25950 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  for databases.**
25960 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73   created using s
25970 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
25980 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69  will be UTF-16 i
25990 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
259a0 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57  e order..**.** W
259b0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
259c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
259d0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
259e0 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
259f0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
25a00 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
25a10 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
25a20 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
25a30 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
25a40 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
25a50 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
25a60 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
25a70 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
25a80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25a90 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
25aa0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
25ab0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
25ac0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
25ad0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
25ae0 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
25af0 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
25b00 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
25b10 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
25b20 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
25b30 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
25b40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
25b50 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
25b60 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
25b70 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
25b80 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
25b90 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
25ba0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
25bb0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
25bc0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
25bd0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
25be0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
25bf0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
25c00 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
25c10 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
25c20 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
25c30 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
25c40 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
25c50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
25c60 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
25c70 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
25c80 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
25c90 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
25ca0 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
25cb0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
25cc0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
25cd0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
25ce0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
25cf0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
25d00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25d10 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
25d20 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
25d30 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
25d40 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
25d50 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
25d60 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
25d70 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
25d80 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
25d90 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
25da0 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
25db0 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
25dc0 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
25dd0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
25de0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
25df0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
25e00 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
25e10 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
25e20 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
25e30 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
25e40 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
25e50 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
25e60 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
25e70 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
25e80 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
25e90 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
25ea0 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
25eb0 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
25ec0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
25ed0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
25ee0 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
25ef0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
25f00 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
25f10 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
25f20 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
25f30 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
25f40 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
25f50 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
25f60 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
25f70 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
25f80 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
25f90 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
25fa0 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
25fb0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
25fc0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
25fd0 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
25fe0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
25ff0 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
26000 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
26010 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
26020 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
26030 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
26040 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
26050 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
26060 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
26070 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
26080 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
26090 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
260a0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
260b0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
260c0 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
260d0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
260e0 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
260f0 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
26100 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
26110 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
26120 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
26130 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
26140 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
26150 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
26160 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
26170 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
26180 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
26190 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
261a0 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
261b0 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
261c0 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
261d0 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
261e0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
261f0 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
26200 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
26210 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
26220 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
26230 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
26240 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
26250 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
26260 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
26270 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
26280 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
26290 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
262a0 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
262b0 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
262c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
262d0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
262e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
262f0 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
26300 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
26310 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
26320 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
26330 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
26340 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
26350 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
26360 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
26370 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
26380 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
26390 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
263a0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
263b0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
263c0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
263d0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
263e0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
263f0 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
26400 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
26410 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
26420 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
26430 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
26440 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
26450 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
26460 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
26470 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
26480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
26490 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
264a0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
264b0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
264c0 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
264d0 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
264e0 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
264f0 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
26500 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
26510 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
26520 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
26530 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
26540 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
26550 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
26560 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
26570 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
26580 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
26590 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
265a0 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
265b0 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
265c0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
265d0 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
265e0 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
265f0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
26600 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
26610 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
26620 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
26630 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
26640 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
26650 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
26660 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
26670 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26680 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
26690 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
266a0 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
266b0 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
266c0 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
266d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
266e0 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
266f0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
26700 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
26710 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
26720 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
26730 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
26740 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
26750 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
26760 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
26770 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
26780 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
26790 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
267a0 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
267b0 20 73 65 74 20 69 6e 20 74 68 65 20 74 68 69 72   set in the thir
267c0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
267d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
267e0 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
267f0 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
26800 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
26810 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
26820 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
26830 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
26840 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
26850 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
26860 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
26870 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
26880 2e 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  ..** URI filenam
26890 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
268a0 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
268b0 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
268c0 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
268d0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
268e0 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
268f0 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
26900 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
26910 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
26920 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
26930 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
26940 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
26950 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
26960 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
26970 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
26980 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
26990 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
269a0 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
269b0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
269c0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
269d0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
269e0 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
269f0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
26a00 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
26a10 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
26a20 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
26a30 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
26a40 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
26a50 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
26a60 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
26a70 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
26a80 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
26a90 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
26aa0 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
26ab0 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
26ac0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
26ad0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
26ae0 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
26af0 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
26b00 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
26b10 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
26b20 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
26b30 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
26b40 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
26b50 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
26b60 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
26b70 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
26b80 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
26b90 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
26ba0 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
26bb0 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
26bc0 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
26bd0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
26be0 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
26bf0 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c  ** ^(On windows,
26c00 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
26c10 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
26c20 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
26c30 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
26c40 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
26c50 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  ).)^.**.** [[cor
26c60 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
26c70 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
26c80 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
26c90 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
26ca0 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
26cb0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
26cc0 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
26cd0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
26ce0 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
26cf0 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
26d00 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
26d10 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75  QLite and its bu
26d20 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69  ilt-in [VFSes] i
26d30 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
26d40 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
26d50 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
26d60 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
26d70 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
26d80 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
26d90 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
26da0 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
26db0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
26dc0 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
26dd0 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
26de0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
26df0 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
26e00 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
26e10 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
26e20 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
26e30 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
26e40 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
26e50 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
26e60 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
26e70 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
26e80 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
26e90 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
26ea0 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
26eb0 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
26ec0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
26ed0 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
26ee0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
26ef0 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
26f00 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
26f10 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
26f20 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
26f30 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
26f40 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
26f50 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
26f60 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
26f70 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
26f80 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
26f90 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
26fa0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
26fb0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
26fc0 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
26fd0 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
26fe0 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
26ff0 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
27000 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
27010 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
27020 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
27030 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
27040 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
27050 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
27060 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
27070 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
27080 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
27090 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
270a0 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
270b0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
270c0 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
270d0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
270e0 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
270f0 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
27100 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
27110 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
27120 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
27130 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
27140 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
27150 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
27160 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
27170 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
27180 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
27190 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
271a0 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
271b0 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
271c0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
271d0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
271e0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
271f0 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
27200 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
27210 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
27220 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
27230 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
27240 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
27250 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
27260 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
27270 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
27280 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
27290 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
272a0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
272b0 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
272c0 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
272d0 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
272e0 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
272f0 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
27300 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
27310 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
27320 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
27330 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
27340 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
27350 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
27360 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
27370 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
27380 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
27390 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
273a0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
273b0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
273c0 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
273d0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
273e0 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
273f0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
27400 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
27410 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
27420 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
27430 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
27440 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
27450 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
27460 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
27470 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
27480 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
27490 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
274a0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
274b0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
274c0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
274d0 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
274e0 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
274f0 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
27500 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
27510 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
27520 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
27530 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
27540 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
27550 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
27560 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
27570 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
27580 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20  HE flag..**.**  
27590 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e  <li> <b>psow</b>
275a0 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61  : ^The psow para
275b0 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20  meter indicates 
275c0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
275d0 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72  he.**     [power
275e0 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20  safe overwrite] 
275f0 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72  property does or
27600 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20   does not apply 
27610 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74  to the.**     st
27620 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77  orage media on w
27630 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73  hich the databas
27640 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a  e file resides..
27650 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
27660 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
27670 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
27680 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
27690 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
276a0 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
276b0 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
276c0 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
276d0 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
276e0 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
276f0 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
27700 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
27710 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
27720 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
27730 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
27740 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
27750 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
27760 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
27770 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
27780 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
27790 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
277a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
277b0 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
277c0 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
277d0 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
277e0 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
277f0 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
27800 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
27810 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
27820 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
27830 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
27840 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
27850 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
27860 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
27870 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
27880 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
27890 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
278a0 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
278b0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
278c0 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
278d0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
278e0 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
278f0 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
27900 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
27910 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
27920 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
27930 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
27940 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
27950 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
27960 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
27970 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
27980 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
27990 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
279a0 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
279b0 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
279c0 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
279d0 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
279e0 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
279f0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
27a00 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
27a10 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
27a20 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
27a30 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
27a40 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
27a50 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
27a60 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
27a70 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
27a80 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
27a90 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
27aa0 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
27ab0 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
27ac0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
27ad0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
27ae0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
27af0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
27b00 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
27b10 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
27b20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
27b30 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
27b40 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
27b50 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
27b60 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
27b70 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
27b80 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
27b90 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
27ba0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
27bb0 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
27bc0 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
27bd0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
27be0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
27bf0 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
27c00 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
27c10 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
27c20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
27c30 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
27c40 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
27c50 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
27c60 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
27c70 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
27c80 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
27c90 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
27ca0 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
27cb0 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
27cc0 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
27cd0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
27ce0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
27cf0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27d00 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
27d10 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
27d20 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
27d30 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
27d40 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
27d50 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
27d60 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
27d70 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
27d80 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
27d90 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
27da0 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
27db0 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
27dc0 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
27dd0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
27de0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
27df0 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
27e00 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
27e10 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
27e20 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
27e30 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
27e40 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
27e50 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
27e60 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
27e70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
27e80 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
27e90 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
27ea0 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
27eb0 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
27ec0 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
27ed0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
27ee0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
27ef0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
27f00 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
27f10 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
27f20 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
27f30 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
27f40 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
27f50 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
27f60 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
27f70 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
27f80 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
27f90 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
27fa0 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
27fb0 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
27fc0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
27fd0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
27fe0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
27ff0 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
28000 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
28010 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
28020 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
28030 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
28040 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
28050 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
28060 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
28070 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
28080 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
28090 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
280a0 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
280b0 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
280c0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
280d0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
280e0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
280f0 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
28100 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
28110 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
28120 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
28130 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
28140 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
28150 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
28160 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
28170 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
28180 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
28190 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
281a0 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
281b0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
281c0 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
281d0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
281e0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
281f0 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
28200 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
28210 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
28220 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
28230 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
28240 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
28250 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
28260 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
28270 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
28280 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
28290 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
282a0 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
282b0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
282c0 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
282d0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
282e0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
282f0 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
28300 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
28310 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
28320 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
28330 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
28340 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
28350 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
28360 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
28370 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
28380 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
28390 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
283a0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
283b0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
283c0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
283d0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
283e0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
283f0 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
28400 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
28410 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
28420 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
28430 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
28440 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
28450 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
28460 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
28470 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
28480 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
28490 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
284a0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
284b0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
284c0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
284d0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
284e0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
284f0 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
28500 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
28510 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
28520 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
28530 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
28540 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
28550 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
28560 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
28570 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
28580 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
28590 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
285a0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
285b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
285c0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
285d0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
285e0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
285f0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
28600 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
28610 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
28620 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
28630 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
28640 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
28650 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
28660 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
28670 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
28680 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
28690 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
286a0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
286b0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
286c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
286d0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
286e0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
286f0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
28700 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
28710 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
28720 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
28730 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
28740 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
28750 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
28760 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
28770 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
28780 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
28790 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
287a0 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
287b0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
287c0 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
287d0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
287e0 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
287f0 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
28800 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
28810 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
28820 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
28830 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
28840 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
28850 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
28860 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
28870 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
28880 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
28890 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
288a0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
288b0 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
288c0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
288d0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
288e0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
288f0 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
28900 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
28910 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
28920 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
28930 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
28940 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
28950 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
28960 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
28970 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
28980 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
28990 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
289a0 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
289b0 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
289c0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
289d0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
289e0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
289f0 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
28a00 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
28a10 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
28a20 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
28a30 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
28a40 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
28a50 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
28a60 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
28a70 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
28a80 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
28a90 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
28aa0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
28ab0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
28ac0 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
28ad0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
28ae0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
28af0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
28b00 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
28b10 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
28b20 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
28b30 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
28b40 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
28b50 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
28b60 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
28b70 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
28b80 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
28b90 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
28ba0 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
28bb0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
28bc0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
28bd0 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
28be0 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
28bf0 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
28c00 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
28c10 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
28c20 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
28c30 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
28c40 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
28c50 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
28c60 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
28c70 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
28c80 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
28c90 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
28ca0 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
28cb0 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
28cc0 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
28cd0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
28ce0 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
28cf0 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
28d00 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
28d10 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
28d20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
28d30 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
28d40 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
28d50 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
28d60 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
28d70 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
28d80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
28d90 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
28da0 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
28db0 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
28dc0 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
28dd0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
28de0 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
28df0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
28e00 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
28e10 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
28e20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
28e30 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
28e40 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
28e50 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
28e60 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
28e70 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
28e80 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
28e90 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
28ea0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
28eb0 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
28ec0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
28ed0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
28ee0 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
28ef0 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
28f00 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
28f10 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
28f20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
28f30 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
28f40 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
28f50 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
28f60 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
28f70 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
28f80 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
28f90 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
28fa0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
28fb0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
28fc0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
28fd0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
28fe0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
28ff0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
29000 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
29010 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
29020 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
29030 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
29040 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
29050 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
29060 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
29070 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
29080 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
29090 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
290a0 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
290b0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
290c0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
290d0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ite3.**.** ^If t
290e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
290f0 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
29100 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
29110 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  h .** [database 
29120 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61  connection] D fa
29130 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73  iled, then the s
29140 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
29150 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
29160 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
29170 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
29180 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65   or [extended re
29190 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
291a0 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e  hat.** API call.
291b0 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20  .** If the most 
291c0 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
291d0 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a  was successful,.
291e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
291f0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
29200 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
29210 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
29220 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
29230 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
29240 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
29250 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
29260 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
29270 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
29280 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
29290 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
292a0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
292b0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
292c0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
292d0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
292e0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
292f0 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
29300 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
29310 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
29320 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
29330 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
29340 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
29350 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
29360 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
29370 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
29380 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
29390 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
293a0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
293b0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
293c0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
293d0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
293e0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
293f0 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
29400 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
29410 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
29420 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
29430 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
29440 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
29450 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
29460 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
29470 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
29480 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29490 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
294a0 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
294b0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
294c0 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
294d0 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
294e0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
294f0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
29500 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
29510 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
29520 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
29530 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
29540 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
29550 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
29560 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
29570 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
29580 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
29590 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
295a0 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
295b0 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
295c0 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
295d0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
295e0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
295f0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
29600 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
29610 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
29620 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
29630 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
29640 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
29650 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
29660 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
29670 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
29680 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
29690 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
296a0 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
296b0 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
296c0 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
296d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
296e0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
296f0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
29700 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
29710 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
29720 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
29730 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
29740 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
29750 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
29760 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
29770 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
29780 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
29790 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
297a0 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
297b0 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
297c0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
297d0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
297e0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
297f0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
29800 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
29810 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
29820 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
29830 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
29840 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
29850 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
29860 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
29870 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
29880 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
29890 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
298a0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
298b0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
298c0 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
298d0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
298e0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
298f0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
29900 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
29910 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
29920 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
29930 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
29940 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
29950 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
29960 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
29970 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
29980 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
29990 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
299a0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
299b0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
299c0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
299d0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
299e0 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
299f0 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
29a00 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
29a10 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
29a20 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
29a30 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
29a40 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
29a50 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
29a60 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
29a70 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
29a80 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
29a90 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
29aa0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
29ab0 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
29ac0 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
29ad0 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
29ae0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
29af0 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
29b00 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
29b10 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
29b20 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
29b30 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
29b40 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
29b50 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
29b60 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
29b70 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
29b80 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
29b90 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
29ba0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
29bb0 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
29bc0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
29bd0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
29be0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
29bf0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
29c00 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
29c10 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
29c20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
29c30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29c40 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
29c50 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
29c60 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
29c70 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
29c80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
29c90 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
29ca0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
29cb0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
29cc0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
29cd0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
29ce0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
29cf0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29d00 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
29d10 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
29d20 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
29d30 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
29d40 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
29d50 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
29d60 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
29d70 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
29d80 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
29d90 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
29da0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
29db0 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
29dc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
29dd0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
29de0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
29df0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
29e00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
29e10 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
29e20 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
29e30 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
29e40 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
29e50 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
29e60 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
29e70 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
29e80 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
29e90 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
29ea0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
29eb0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
29ec0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
29ed0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
29ee0 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
29ef0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
29f00 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
29f10 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
29f20 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
29f30 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
29f40 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
29f50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
29f60 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
29f70 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
29f80 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
29f90 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
29fa0 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
29fb0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
29fc0 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
29fd0 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
29fe0 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
29ff0 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
2a000 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
2a010 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
2a020 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
2a030 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
2a040 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
2a050 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
2a060 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
2a070 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
2a080 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
2a090 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
2a0a0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
2a0b0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
2a0c0 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
2a0d0 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
2a0e0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
2a0f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2a100 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
2a110 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
2a120 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
2a130 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
2a140 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
2a150 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
2a160 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
2a170 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
2a180 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
2a190 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
2a1a0 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
2a1b0 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
2a1c0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
2a1d0 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
2a1e0 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
2a1f0 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
2a200 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
2a210 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
2a220 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
2a230 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
2a240 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
2a250 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
2a260 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
2a270 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
2a280 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
2a290 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
2a2a0 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
2a2b0 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
2a2c0 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
2a2d0 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
2a2e0 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
2a2f0 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
2a300 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
2a310 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
2a320 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
2a330 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
2a340 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
2a350 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
2a360 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
2a370 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
2a380 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
2a390 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
2a3a0 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
2a3b0 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
2a3c0 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
2a3d0 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
2a3e0 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
2a3f0 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
2a400 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
2a410 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
2a420 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
2a430 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
2a440 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
2a450 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
2a460 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
2a470 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
2a480 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
2a490 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
2a4a0 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
2a4b0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
2a4c0 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
2a4d0 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
2a4e0 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
2a4f0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
2a500 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
2a510 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
2a520 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
2a530 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
2a540 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
2a550 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
2a560 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
2a570 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
2a580 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
2a590 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
2a5a0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
2a5b0 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
2a5c0 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
2a5d0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
2a5e0 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
2a5f0 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
2a600 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
2a610 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
2a620 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
2a630 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
2a640 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
2a650 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
2a660 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2a670 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
2a680 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
2a690 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
2a6a0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
2a6b0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
2a6c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a6d0 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
2a6e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a6f0 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
2a700 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
2a710 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
2a720 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
2a730 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a740 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
2a750 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a760 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
2a770 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2a780 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
2a790 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
2a7a0 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
2a7b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a7c0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
2a7d0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a7e0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
2a7f0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a800 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2a810 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
2a820 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
2a830 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
2a840 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
2a850 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
2a860 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2a870 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
2a880 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
2a890 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
2a8a0 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
2a8b0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a8c0 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
2a8d0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2a8e0 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
2a8f0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2a900 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
2a910 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
2a920 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
2a930 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a940 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
2a950 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
2a960 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
2a970 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
2a980 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a990 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2a9a0 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
2a9b0 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
2a9c0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
2a9d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2a9e0 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
2a9f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2aa00 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
2aa10 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2aa20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
2aa30 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
2aa40 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
2aa50 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
2aa60 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
2aa70 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b  statement.  If [
2aa80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2aa90 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20  v2()] or.** the 
2aaa0 65 71 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73  equivalent tries
2aab0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61   to allocate spa
2aac0 63 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e  ce for more than
2aad0 20 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64   this many opcod
2aae0 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c  es.** in a singl
2aaf0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2ab00 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f  ment, an SQLITE_
2ab10 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72  NOMEM error is r
2ab20 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
2ab30 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2ab40 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2ab50 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
2ab60 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2ab70 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
2ab80 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
2ab90 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2aba0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
2abb0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2abc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
2abd0 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
2abe0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
2abf0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
2ac00 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2ac10 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
2ac20 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
2ac30 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
2ac40 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
2ac50 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
2ac60 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
2ac70 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
2ac80 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
2ac90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2aca0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2acb0 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
2acc0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
2acd0 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
2ace0 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
2acf0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2ad00 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2ad10 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
2ad20 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2ad30 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
2ad40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2ad50 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
2ad60 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
2ad70 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
2ad80 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
2ad90 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2ada0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
2adb0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2adc0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
2add0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
2ade0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
2adf0 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
2ae00 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
2ae10 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2ae20 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
2ae30 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74  _THREADS]] ^(<dt
2ae40 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  >SQLITE_LIMIT_WO
2ae50 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74  RKER_THREADS</dt
2ae60 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2ae70 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
2ae80 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20  uxiliary worker 
2ae90 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73  threads that a s
2aea0 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72  ingle.** [prepar
2aeb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61  ed statement] ma
2aec0 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a  y start.</dd>)^.
2aed0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
2aee0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2aef0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
2af00 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
2af10 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2af20 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
2af30 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
2af40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2af50 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
2af60 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
2af70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2af80 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
2af90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
2afa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2afb0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
2afc0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
2afd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2afe0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
2aff0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b000 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
2b010 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2b020 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
2b030 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
2b040 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
2b050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b060 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
2b070 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
2b080 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
2b090 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
2b0a0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2b0b0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
2b0c0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
2b0d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2b0e0 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
2b0f0 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
2b100 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
2b110 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20  ER_THREADS      
2b120 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43       11../*.** C
2b130 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
2b140 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Flags.**.** The
2b150 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
2b160 69 6e 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67  ine various flag
2b170 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 61  s that can be pa
2b180 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72  ssed into.** "pr
2b190 65 70 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74  epFlags" paramet
2b1a0 65 72 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  er of the [sqlit
2b1b0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d  e3_prepare_v3()]
2b1c0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2b1d0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
2b1e0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a   interfaces..**.
2b1f0 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79  ** New flags may
2b200 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
2b210 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
2b220 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64  SQLite..**.** <d
2b230 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50  l>.** [[SQLITE_P
2b240 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2b250 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
2b260 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54  _PREPARE_PERSIST
2b270 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ENT</dt>.** <dd>
2b280 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  The SQLITE_PREPA
2b290 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c  RE_PERSISTENT fl
2b2a0 61 67 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20  ag is a hint to 
2b2b0 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  the query planne
2b2c0 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
2b2d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b2e0 20 77 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65   will be retaine
2b2f0 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d  d for a long tim
2b300 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c  e and.** probabl
2b310 79 20 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69  y reused many ti
2b320 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20  mes.)^ ^Without 
2b330 74 68 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69  this flag, [sqli
2b340 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2b350 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2b360 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
2b370 5d 20 61 73 73 75 6d 65 20 74 68 61 74 20 74 68  ] assume that th
2b380 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2b390 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65  ment will .** be
2b3a0 20 75 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20   used just once 
2b3b0 6f 72 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77  or at most a few
2b3c0 20 74 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20   times and then 
2b3d0 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a  destroyed using.
2b3e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2b3f0 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65  lize()] relative
2b400 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72  ly soon. The cur
2b410 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
2b420 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74  ion acts.** on t
2b430 68 69 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69  his hint by avoi
2b440 64 69 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20  ding the use of 
2b450 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
2b460 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a  y] so as not to.
2b470 2a 2a 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c  ** deplete the l
2b480 69 6d 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20  imited store of 
2b490 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
2b4a0 2e 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e  . Future version
2b4b0 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  s of.** SQLite m
2b4c0 61 79 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68  ay act on this h
2b4d0 69 6e 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e  int differently.
2b4e0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
2b4f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50  fine SQLITE_PREP
2b500 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 20  ARE_PERSISTENT  
2b510 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 31              0x01
2b520 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b530 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
2b540 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
2b550 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
2b560 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
2b570 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  r}.** METHOD: sq
2b580 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55  lite3.** CONSTRU
2b590 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
2b5a0 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  mt.**.** To exec
2b5b0 75 74 65 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ute an SQL state
2b5c0 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74 20 66 69  ment, it must fi
2b5d0 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
2b5e0 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
2b5f0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
2b600 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
2b610 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20 69 6e  outines.  Or, in
2b620 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2b630 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
2b640 61 72 65 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  are constructors
2b650 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2b660 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
2b670 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ject..**.** The 
2b680 70 72 65 66 65 72 72 65 64 20 72 6f 75 74 69 6e  preferred routin
2b690 65 20 74 6f 20 75 73 65 20 69 73 20 5b 73 71 6c  e to use is [sql
2b6a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2b6b0 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  )].  The.** [sql
2b6c0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2b6d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6c 65 67  interface is leg
2b6e0 61 63 79 20 61 6e 64 20 73 68 6f 75 6c 64 20 62  acy and should b
2b6f0 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73  e avoided..** [s
2b700 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b710 33 28 29 5d 20 68 61 73 20 61 6e 20 65 78 74 72  3()] has an extr
2b720 61 20 22 70 72 65 70 46 6c 61 67 73 22 20 6f 70  a "prepFlags" op
2b730 74 69 6f 6e 20 74 68 61 74 20 69 73 20 75 73 65  tion that is use
2b740 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69 61 6c  d.** for special
2b750 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
2b760 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
2b770 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 73  UTF-8 interfaces
2b780 20 69 73 20 70 72 65 66 65 72 72 65 64 2c 20 61   is preferred, a
2b790 73 20 53 51 4c 69 74 65 20 63 75 72 72 65 6e 74  s SQLite current
2b7a0 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c 20 70  ly.** does all p
2b7b0 61 72 73 69 6e 67 20 75 73 69 6e 67 20 55 54 46  arsing using UTF
2b7c0 2d 38 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20  -8.  The UTF-16 
2b7d0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
2b7e0 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20 61 20  rovided.** as a 
2b7f0 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20 54 68  convenience.  Th
2b800 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61  e UTF-16 interfa
2b810 63 65 73 20 77 6f 72 6b 20 62 79 20 63 6f 6e 76  ces work by conv
2b820 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20 69 6e  erting the.** in
2b830 70 75 74 20 74 65 78 74 20 69 6e 74 6f 20 55 54  put text into UT
2b840 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 69  F-8, then invoki
2b850 6e 67 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ng the correspon
2b860 64 69 6e 67 20 55 54 46 2d 38 20 69 6e 74 65 72  ding UTF-8 inter
2b870 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  face..**.** The 
2b880 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
2b890 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
2b8a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b8b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
2b8c0 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
2b8d0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
2b8e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2b8f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2b900 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2b910 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
2b920 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2b930 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
2b940 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
2b950 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
2b960 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
2b970 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
2b980 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2b990 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
2b9a0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
2b9b0 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
2b9c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2b9d0 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ), sqlite3_prepa
2b9e0 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  re_v2(),.** and 
2b9f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ba00 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v3().** interfac
2ba10 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
2ba20 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2ba30 65 31 36 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  e16(), sqlite3_p
2ba40 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a  repare16_v2(),.*
2ba50 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  * and sqlite3_pr
2ba60 65 70 61 72 65 31 36 5f 76 33 28 29 20 75 73 65  epare16_v3() use
2ba70 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
2ba80 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
2ba90 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76  ument is negativ
2baa0 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  e, then zSql is 
2bab0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
2bac0 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
2bad0 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
2bae0 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20  te is positive, 
2baf0 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a  then it is the.*
2bb00 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
2bb10 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
2bb20 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  .  ^If nByte is 
2bb30 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72  zero, then no pr
2bb40 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2bb50 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64  ent is generated
2bb60 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c  ..** If the call
2bb70 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68  er knows that th
2bb80 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
2bb90 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
2bba0 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ted, then.** the
2bbb0 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65  re is a small pe
2bbc0 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
2bbd0 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61  age to passing a
2bbe0 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
2bbf0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65  r that.** is the
2bc00 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2bc10 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
2bc20 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
2bc30 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
2bc40 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a  -terminator..**.
2bc50 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
2bc60 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
2bc70 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
2bc80 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
2bc90 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
2bca0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
2bcb0 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
2bcc0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
2bcd0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
2bce0 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
2bcf0 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
2bd00 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
2bd10 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
2bd20 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
2bd30 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
2bd40 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
2bd50 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
2bd60 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
2bd70 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
2bd80 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
2bd90 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
2bda0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2bdb0 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
2bdc0 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
2bdd0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
2bde0 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
2bdf0 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
2be00 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
2be10 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
2be20 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
2be30 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
2be40 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
2be50 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
2be60 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
2be70 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
2be80 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
2be90 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
2bea0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
2beb0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2bec0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
2bed0 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
2bee0 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
2bef0 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
2bf00 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
2bf10 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
2bf20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
2bf30 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
2bf40 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
2bf50 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
2bf60 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
2bf70 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
2bf80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2bf90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c  e3_prepare_v2(),
2bfa0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2bfb0 5f 76 33 28 29 2c 20 73 71 6c 69 74 65 33 5f 70  _v3(), sqlite3_p
2bfc0 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a  repare16_v2(),.*
2bfd0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  * and sqlite3_pr
2bfe0 65 70 61 72 65 31 36 5f 76 33 28 29 20 69 6e 74  epare16_v3() int
2bff0 65 72 66 61 63 65 73 20 61 72 65 20 72 65 63 6f  erfaces are reco
2c000 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
2c010 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a  new programs..**
2c020 20 54 68 65 20 6f 6c 64 65 72 20 69 6e 74 65 72   The older inter
2c030 66 61 63 65 73 20 28 73 71 6c 69 74 65 33 5f 70  faces (sqlite3_p
2c040 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
2c050 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2c060 29 0a 2a 2a 20 61 72 65 20 72 65 74 61 69 6e 65  ).** are retaine
2c070 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
2c080 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
2c090 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
2c0a0 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
2c0b0 5e 49 6e 20 74 68 65 20 22 76 58 22 20 69 6e 74  ^In the "vX" int
2c0c0 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
2c0d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2c0e0 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
2c0f0 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
2c100 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
2c110 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
2c120 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
2c130 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
2c140 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
2c150 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
2c160 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
2c170 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
2c180 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
2c190 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
2c1a0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
2c1b0 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
2c1c0 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
2c1d0 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
2c1e0 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
2c1f0 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
2c200 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
2c210 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
2c220 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
2c230 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
2c240 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2c250 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
2c260 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
2c270 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
2c280 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
2c290 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
2c2a0 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
2c2b0 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
2c2c0 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
2c2d0 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
2c2e0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
2c2f0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
2c300 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2c310 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
2c320 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
2c330 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
2c340 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
2c350 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
2c360 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
2c370 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
2c380 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c390 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
2c3a0 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
2c3b0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
2c3c0 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
2c3d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2c3e0 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
2c3f0 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
2c400 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2c410 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
2c420 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
2c430 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
2c440 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
2c450 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
2c460 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
2c470 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
2c480 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
2c490 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
2c4a0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
2c4b0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2c4c0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
2c4d0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
2c4e0 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
2c4f0 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
2c500 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
2c510 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
2c520 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
2c530 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
2c540 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
2c550 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
2c560 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
2c570 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
2c580 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
2c590 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
2c5a0 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
2c5b0 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
2c5c0 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
2c5d0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
2c5e0 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
2c5f0 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
2c600 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
2c610 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
2c620 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
2c630 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
2c640 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
2c650 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
2c660 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
2c670 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
2c680 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
2c690 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2c6a0 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
2c6b0 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
2c6c0 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
2c6d0 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
2c6e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
2c6f0 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
2c700 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
2c710 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
2c720 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
2c730 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2c740 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
2c750 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
2c760 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65 70 61  p>^sqlite3_prepa
2c770 72 65 5f 76 33 28 29 20 64 69 66 66 65 72 73 20  re_v3() differs 
2c780 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72 65  from sqlite3_pre
2c790 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20 69  pare_v2() only i
2c7a0 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65 20  n having.** the 
2c7b0 65 78 74 72 61 20 70 72 65 70 46 6c 61 67 73 20  extra prepFlags 
2c7c0 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68  parameter, which
2c7d0 20 69 73 20 61 20 62 69 74 20 61 72 72 61 79 20   is a bit array 
2c7e0 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a 65  consisting of ze
2c7f0 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f 66  ro or.** more of
2c800 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50 52 45   the [SQLITE_PRE
2c810 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 7c  PARE_PERSISTENT|
2c820 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 2a  SQLITE_PREPARE_*
2c830 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a 2a  ] flags.  ^The.*
2c840 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
2c850 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
2c860 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 74   works exactly t
2c870 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
2c880 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2c890 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f 20 70  () with a zero p
2c8a0 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74  repFlags paramet
2c8b0 65 72 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  er..** </ol>.*/.
2c8c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2c8d0 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
2c8e0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2c8f0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2c900 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2c910 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2c920 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2c930 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2c940 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2c950 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2c960 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2c970 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2c980 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2c990 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2c9a0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2c9b0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2c9c0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2c9d0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2c9e0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2c9f0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2ca00 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2ca10 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
2ca20 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2ca30 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2ca40 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2ca50 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2ca60 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2ca70 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2ca80 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2ca90 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2caa0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2cab0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2cac0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2cad0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2cae0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2caf0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2cb00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2cb10 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2cb20 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2cb30 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2cb40 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2cb50 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2cb60 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2cb70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2cb80 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2cb90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2cba0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2cbb0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2cbc0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2cbd0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2cbe0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2cbf0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2cc00 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2cc10 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72   unsigned int pr
2cc20 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f  epFlags, /* Zero
2cc30 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f   or more SQLITE_
2cc40 50 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a  PREPARE_ flags *
2cc50 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2cc60 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2cc70 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2cc80 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2cc90 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2cca0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2ccb0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2ccc0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2ccd0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2cce0 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
2ccf0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2cd00 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2cd10 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2cd20 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
2cd30 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2cd40 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
2cd50 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2cd60 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2cd70 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2cd80 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2cd90 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2cda0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2cdb0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2cdc0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2cdd0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
2cde0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2cdf0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2ce00 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2ce10 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
2ce20 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2ce30 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2ce40 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2ce50 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2ce60 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2ce70 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2ce80 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2ce90 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
2cea0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2ceb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2cec0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2ced0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2cee0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2cef0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2cf00 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2cf10 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2cf20 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
2cf30 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2cf40 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2cf50 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2cf60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2cf70 70 61 72 65 31 36 5f 76 33 28 0a 20 20 73 71 6c  pare16_v3(.  sql
2cf80 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2cf90 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2cfa0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2cfb0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
2cfc0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2cfd0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
2cfe0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2cff0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2d000 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2d010 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2d020 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69  bytes. */.  unsi
2d030 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61  gned int prepFla
2d040 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d  gs, /* Zero or m
2d050 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ore SQLITE_PREPA
2d060 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73  RE_ flags */.  s
2d070 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2d080 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2d090 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2d0a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2d0b0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2d0c0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2d0d0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2d0e0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
2d0f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2d100 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
2d110 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44  nt SQL.** METHOD
2d120 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2d130 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d140 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  3_sql(P) interfa
2d150 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2d160 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f  nter to a copy o
2d170 66 20 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53  f the UTF-8.** S
2d180 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
2d190 63 72 65 61 74 65 20 5b 70 72 65 70 61 72 65 64  create [prepared
2d1a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66   statement] P if
2d1b0 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65   P was.** create
2d1c0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  d by [sqlite3_pr
2d1d0 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
2d1e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2d1f0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2d200 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2d210 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  , or [sqlite3_pr
2d220 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a  epare16_v3()]..*
2d230 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2d240 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69  xpanded_sql(P) i
2d250 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d260 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2d270 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
2d280 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53  containing the S
2d290 51 4c 20 74 65 78 74 20 6f 66 20 70 72 65 70 61  QL text of prepa
2d2a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2d2b0 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70  with.** [bound p
2d2c0 61 72 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e  arameters] expan
2d2d0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2d2e0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70   example, if a p
2d2f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d300 74 20 69 73 20 63 72 65 61 74 65 64 20 75 73 69  t is created usi
2d310 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65  ng the SQL.** te
2d320 78 74 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c  xt "SELECT $abc,
2d330 3a 78 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72  :xyz" and if par
2d340 61 6d 65 74 65 72 20 24 61 62 63 20 69 73 20 62  ameter $abc is b
2d350 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20  ound to integer 
2d360 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61  2345.** and para
2d370 6d 65 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e  meter :xyz is un
2d380 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69  bound, then sqli
2d390 74 65 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72  te3_sql() will r
2d3a0 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69  eturn.** the ori
2d3b0 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53  ginal string, "S
2d3c0 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2d3d0 20 62 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70   but sqlite3_exp
2d3e0 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77  anded_sql().** w
2d3f0 69 6c 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45  ill return "SELE
2d400 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e  CT 2345,NULL".)^
2d410 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2d420 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2d430 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
2d440 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73  urns NULL if ins
2d450 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
2d460 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65  .** is available
2d470 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
2d480 75 6c 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ult, or if the r
2d490 65 73 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65  esult would exce
2d4a0 65 64 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61  ed the.** the ma
2d4b0 78 69 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e  ximum string len
2d4c0 67 74 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62  gth determined b
2d4d0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49  y the [SQLITE_LI
2d4e0 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a  MIT_LENGTH]..**.
2d4f0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
2d500 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
2d510 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2d520 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65  ption limits the
2d530 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e   size of.** boun
2d540 64 20 70 61 72 61 6d 65 74 65 72 20 65 78 70 61  d parameter expa
2d550 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53  nsions.  ^The [S
2d560 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45  QLITE_OMIT_TRACE
2d570 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
2d580 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20  * option causes 
2d590 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2d5a0 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73  _sql() to always
2d5b0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a   return NULL..**
2d5c0 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20  .** ^The string 
2d5d0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2d5e0 74 65 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61  te3_sql(P) is ma
2d5f0 6e 61 67 65 64 20 62 79 20 53 51 4c 69 74 65 20  naged by SQLite 
2d600 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  and is.** automa
2d610 74 69 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68  tically freed wh
2d620 65 6e 20 74 68 65 20 70 72 65 70 61 72 65 64 20  en the prepared 
2d630 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e  statement is fin
2d640 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  alized..** ^The 
2d650 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20  string returned 
2d660 62 79 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  by sqlite3_expan
2d670 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74  ded_sql(P), on t
2d680 68 65 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a  he other hand,.*
2d690 2a 20 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72  * is obtained fr
2d6a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2d6b0 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62  oc()] and must b
2d6c0 65 20 66 72 65 65 20 62 79 20 74 68 65 20 61 70  e free by the ap
2d6d0 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20  plication.** by 
2d6e0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
2d6f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2d700 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2d710 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74  qlite3_sql(sqlit
2d720 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2d730 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65  .char *sqlite3_e
2d740 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69  xpanded_sql(sqli
2d750 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2d760 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d770 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2d780 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2d790 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
2d7a0 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  base.** METHOD: 
2d7b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2d7c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d7d0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
2d7e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2d7f0 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2d800 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
2d810 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
2d820 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
2d830 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
2d840 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
2d850 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2d860 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
2d870 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2d880 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2d890 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2d8a0 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
2d8b0 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
2d8c0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2d8d0 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
2d8e0 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
2d8f0 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
2d900 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
2d910 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
2d920 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
2d930 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
2d940 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
2d950 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
2d960 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
2d970 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
2d980 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2d990 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
2d9a0 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
2d9b0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2d9c0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
2d9d0 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
2d9e0 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
2d9f0 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
2da00 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
2da10 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
2da20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2da30 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
2da40 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2da50 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
2da60 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
2da70 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
2da80 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
2da90 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
2daa0 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
2dab0 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
2dac0 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
2dad0 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
2dae0 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
2daf0 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
2db00 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
2db10 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2db20 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
2db30 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
2db40 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
2db50 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
2db60 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2db70 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
2db80 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
2db90 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
2dba0 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
2dbb0 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
2dbc0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
2dbd0 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
2dbe0 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
2dbf0 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
2dc00 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2dc10 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
2dc20 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
2dc30 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
2dc40 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
2dc50 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
2dc60 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
2dc70 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
2dc80 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
2dc90 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
2dca0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2dcb0 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
2dcc0 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20  n disk..** ^The 
2dcd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2dce0 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63  donly() interfac
2dcf0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 66  e returns true f
2dd00 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65  or [BEGIN] since
2dd10 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65  .** [BEGIN] mere
2dd20 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c  ly sets internal
2dd30 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20   flags, but the 
2dd40 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d  [BEGIN|BEGIN IMM
2dd50 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b  EDIATE] and.** [
2dd60 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c  BEGIN|BEGIN EXCL
2dd70 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20  USIVE] commands 
2dd80 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 74  do touch the dat
2dd90 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20  abase and so.** 
2dda0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2ddb0 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20  donly() returns 
2ddc0 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20  false for those 
2ddd0 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74  commands..*/.int
2dde0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2ddf0 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
2de00 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2de10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2de20 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65  termine If A Pre
2de30 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2de40 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a  Has Been Reset.*
2de50 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2de60 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2de70 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  e sqlite3_stmt_b
2de80 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65  usy(S) interface
2de90 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
2dea0 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a  on-zero) if the.
2deb0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2dec0 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65  tement] S has be
2ded0 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65  en stepped at le
2dee0 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a  ast once using .
2def0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2df00 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69  (S)] but has nei
2df10 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70  ther run to comp
2df20 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64  letion (returned
2df30 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2df40 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  ] from [sqlite3_
2df50 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a  step(S)]) nor.**
2df60 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
2df70 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2df80 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
2df90 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2dfa0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
2dfb0 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
2dfc0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2dfd0 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
2dfe0 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
2dff0 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
2e000 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
2e010 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
2e020 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
2e030 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
2e040 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2e050 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
2e060 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
2e070 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
2e080 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
2e090 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
2e0a0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2e0b0 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
2e0c0 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
2e0d0 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
2e0e0 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
2e0f0 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
2e100 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
2e110 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
2e120 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
2e130 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
2e140 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
2e150 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
2e160 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
2e170 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
2e180 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
2e190 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
2e1a0 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
2e1b0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2e1c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2e1d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e1e0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
2e1f0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
2e200 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
2e210 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e220 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
2e230 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e240 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
2e250 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
2e260 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
2e270 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
2e280 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
2e290 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
2e2a0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
2e2b0 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
2e2c0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
2e2d0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
2e2e0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
2e2f0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
2e300 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2e310 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
2e320 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
2e330 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
2e340 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
2e350 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
2e360 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e370 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
2e380 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
2e390 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
2e3a0 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
2e3b0 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
2e3c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e3d0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
2e3e0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
2e3f0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
2e400 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
2e410 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2e420 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
2e430 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
2e440 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
2e450 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
2e460 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
2e470 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
2e480 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
2e490 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e4a0 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  value.  The.** [
2e4b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
2e4c0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  p()] interface c
2e4d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f  an be used to co
2e4e0 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a  nstruct a new .*
2e4f0 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  * protected sqli
2e500 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61  te3_value from a
2e510 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2e520 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
2e530 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
2e540 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
2e550 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
2e560 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
2e570 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
2e580 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
2e590 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
2e5a0 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
2e5b0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2e5c0 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
2e5d0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
2e5e0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2e5f0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2e600 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
2e610 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
2e620 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
2e630 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
2e640 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
2e650 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
2e660 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
2e670 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
2e680 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
2e690 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
2e6a0 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
2e6b0 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
2e6c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2e6d0 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
2e6e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2e6f0 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
2e700 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
2e710 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2e720 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2e730 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2e740 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e750 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
2e760 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
2e770 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
2e780 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
2e790 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
2e7a0 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
2e7b0 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
2e7c0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
2e7d0 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
2e7e0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
2e7f0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
2e800 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2e810 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e820 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
2e830 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
2e840 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2e850 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2e860 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
2e870 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
2e880 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
2e890 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
2e8a0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2e8b0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2e8c0 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
2e8d0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2e8e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
2e8f0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2e900 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2e910 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
2e920 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
2e930 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e940 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
2e950 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 61 73 20  only be used as 
2e960 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20  arguments.** to 
2e970 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2e980 76 61 6c 75 65 28 29 5d 2c 20 5b 73 71 6c 69 74  value()], [sqlit
2e990 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2e9a0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2e9b0 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 0a  3_value_dup()]..
2e9c0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
2e9d0 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
2e9e0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
2e9f0 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
2ea00 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
2ea10 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
2ea20 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2ea30 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
2ea40 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 61  truct sqlite3_va
2ea50 6c 75 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  lue sqlite3_valu
2ea60 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
2ea70 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
2ea80 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
2ea90 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
2eaa0 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
2eab0 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
2eac0 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
2ead0 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
2eae0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
2eaf0 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
2eb00 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2eb10 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
2eb20 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
2eb30 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
2eb40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2eb50 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2eb60 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
2eb70 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2eb80 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2eb90 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
2eba0 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
2ebb0 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
2ebc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2ebd0 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
2ebe0 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
2ebf0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2ec00 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
2ec10 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2ec20 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
2ec30 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2ec40 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
2ec50 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
2ec60 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
2ec70 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2ec80 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
2ec90 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
2eca0 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
2ecb0 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
2ecc0 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
2ecd0 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
2ece0 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
2ecf0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
2ed00 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
2ed10 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
2ed20 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
2ed30 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
2ed40 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
2ed50 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
2ed60 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
2ed70 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ding}.** METHOD:
2ed80 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2ed90 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
2eda0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
2edb0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
2edc0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2edd0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
2ede0 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
2edf0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
2ee00 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
2ee10 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
2ee20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
2ee30 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
2ee40 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
2ee50 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
2ee60 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
2ee70 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
2ee80 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
2ee90 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
2eea0 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
2eeb0 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
2eec0 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
2eed0 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
2eee0 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
2eef0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
2ef00 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
2ef10 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
2ef20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
2ef30 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
2ef40 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
2ef50 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
2ef60 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
2ef70 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
2ef80 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2ef90 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
2efa0 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
2efb0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2efc0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2efd0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
2efe0 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
2eff0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
2f000 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2f010 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
2f020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2f030 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
2f040 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
2f050 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
2f060 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2f070 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
2f080 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
2f090 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
2f0a0 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
2f0b0 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2f0c0 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
2f0d0 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
2f0e0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
2f0f0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
2f100 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
2f110 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
2f120 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
2f130 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
2f140 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
2f150 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
2f160 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
2f170 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
2f180 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
2f190 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2f1a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2f1b0 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
2f1c0 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
2f1d0 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
2f1e0 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
2f1f0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
2f200 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
2f210 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
2f220 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
2f230 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
2f240 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
2f250 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2f260 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
2f270 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
2f280 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
2f290 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
2f2a0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
2f2b0 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
2f2c0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
2f2d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
2f2e0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2f2f0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2f300 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2f310 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2f320 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55  d_blob() is a NU
2f330 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
2f340 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2f350 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72  eter.** is ignor
2f360 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72  ed and the end r
2f370 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d  esult is the sam
2f380 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e  e as sqlite3_bin
2f390 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20  d_null()..**.** 
2f3a0 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
2f3b0 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
2f3c0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
2f3d0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
2f3e0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
2f3f0 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
2f400 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
2f410 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
2f420 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2f430 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
2f440 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
2f450 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2f460 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
2f470 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
2f480 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2f490 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2f4a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2f4b0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
2f4c0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
2f4d0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
2f4e0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
2f4f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2f500 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
2f510 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2f520 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
2f530 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2f540 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2f550 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
2f560 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
2f570 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2f580 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
2f590 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
2f5a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
2f5b0 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
2f5c0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
2f5d0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2f5e0 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c  _text16() or sql
2f5f0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2f600 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20  () then.** that 
2f610 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
2f620 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
2f630 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
2f640 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
2f650 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
2f660 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
2f670 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
2f680 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
2f690 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
2f6a0 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
2f6b0 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
2f6c0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2f6d0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2f6e0 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
2f6f0 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
2f700 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
2f710 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
2f720 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
2f730 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
2f740 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
2f750 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
2f760 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
2f770 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
2f780 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
2f790 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72  the BLOB and str
2f7a0 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65  ing binding inte
2f7b0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64  rfaces.** is a d
2f7c0 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
2f7d0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2f7e0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
2f7f0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
2f800 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2f810 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
2f820 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
2f830 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
2f840 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
2f850 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
2f860 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50   call to bind AP
2f870 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20  I fails..** ^If 
2f880 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2f890 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
2f8a0 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
2f8b0 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
2f8c0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
2f8d0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
2f8e0 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
2f8f0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
2f900 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
2f910 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
2f920 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
2f930 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
2f940 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
2f950 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
2f960 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
2f970 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
2f980 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
2f990 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
2f9a0 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
2f9b0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2f9c0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2f9d0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
2f9e0 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
2f9f0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2fa00 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f  xt64() must be o
2fa10 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45  ne of.** [SQLITE
2fa20 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
2fa30 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
2fa40 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
2fa50 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a  LITE_UTF16LE].**
2fa60 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
2fa70 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
2fa80 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72  text in the thir
2fa90 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  d parameter.  If
2faa0 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72  .** the sixth ar
2fab0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2fac0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2fad0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
2fae0 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c  e.** allowed val
2faf0 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c  ues shown above,
2fb00 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20   or if the text 
2fb10 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
2fb20 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68  erent.** from th
2fb30 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
2fb40 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74  fied by the sixt
2fb50 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  h parameter, the
2fb60 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
2fb70 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
2fb80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2fb90 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
2fba0 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
2fbb0 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
2fbc0 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
2fbd0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
2fbe0 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
2fbf0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
2fc00 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
2fc10 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
2fc20 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
2fc30 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
2fc40 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
2fc50 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
2fc60 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
2fc70 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
2fc80 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
2fc90 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
2fca0 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
2fcb0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2fcc0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
2fcd0 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
2fce0 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
2fcf0 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
2fd00 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
2fd10 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
2fd20 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
2fd30 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  B..**.** ^The sq
2fd40 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74  lite3_bind_point
2fd50 65 72 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72 6f  er(S,I,P,T,D) ro
2fd60 75 74 69 6e 65 20 63 61 75 73 65 73 20 74 68 65  utine causes the
2fd70 20 49 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   I-th parameter 
2fd80 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  in.** [prepared 
2fd90 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20  statement] S to 
2fda0 68 61 76 65 20 61 6e 20 53 51 4c 20 76 61 6c 75  have an SQL valu
2fdb0 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20 74  e of NULL, but t
2fdc0 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73 73  o also be.** ass
2fdd0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
2fde0 20 70 6f 69 6e 74 65 72 20 50 20 6f 66 20 74 79   pointer P of ty
2fdf0 70 65 20 54 2e 20 20 5e 44 20 69 73 20 65 69 74  pe T.  ^D is eit
2fe00 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
2fe10 65 72 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e 74  er or.** a point
2fe20 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63 74  er to a destruct
2fe30 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20  or function for 
2fe40 50 2e 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  P. ^SQLite will 
2fe50 69 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64 65  invoke the.** de
2fe60 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20  structor D with 
2fe70 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
2fe80 74 20 6f 66 20 50 20 77 68 65 6e 20 69 74 20 69  t of P when it i
2fe90 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
2fea0 0a 2a 2a 20 50 2e 20 20 54 68 65 20 54 20 70 61  .** P.  The T pa
2feb0 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62  rameter should b
2fec0 65 20 61 20 73 74 61 74 69 63 20 73 74 72 69 6e  e a static strin
2fed0 67 2c 20 70 72 65 66 65 72 61 62 6c 79 20 61 20  g, preferably a 
2fee0 73 74 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72 61  string.** litera
2fef0 6c 2e 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  l. The sqlite3_b
2ff00 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f  ind_pointer() ro
2ff10 75 74 69 6e 65 20 69 73 20 70 61 72 74 20 6f 66  utine is part of
2ff20 20 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65 72   the.** [pointer
2ff30 20 70 61 73 73 69 6e 67 20 69 6e 74 65 72 66 61   passing interfa
2ff40 63 65 5d 20 61 64 64 65 64 20 66 6f 72 20 53 51  ce] added for SQ
2ff50 4c 69 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a 0a  Lite 3.20.0..**.
2ff60 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
2ff70 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2ff80 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
2ff90 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
2ffa0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
2ffb0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2ffc0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
2ffd0 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
2ffe0 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
2fff0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
30000 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
30010 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
30020 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
30030 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
30040 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
30050 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
30060 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
30070 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
30080 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
30090 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
300a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
300b0 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
300c0 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
300d0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
300e0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
300f0 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
30100 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
30110 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
30120 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30130 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
30140 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
30150 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
30160 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
30170 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
30180 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
30190 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
301a0 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
301b0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
301c0 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
301d0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
301e0 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67  LITE_TOOBIG] mig
301f0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69  ht be returned i
30200 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20  f the size of a 
30210 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a  string or BLOB.*
30220 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73  * exceeds limits
30230 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c   imposed by [sql
30240 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
30250 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
30260 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  ]) or.** [SQLITE
30270 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a  _MAX_LENGTH]..**
30280 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
30290 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
302a0 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
302b0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
302c0 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
302d0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
302e0 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
302f0 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
30300 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
30310 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30320 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
30330 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30340 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
30350 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
30360 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
30370 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
30380 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
30390 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
303a0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
303b0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
303c0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
303d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71  3_bind_blob64(sq
303e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
303f0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73  , const void*, s
30400 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
30410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30420 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
30430 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
30440 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28  te3_bind_double(
30450 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30460 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74  nt, double);.int
30470 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
30480 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
30490 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20   int, int);.int 
304a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
304b0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
304c0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
304d0 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74  nt64);.int sqlit
304e0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
304f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
30500 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
30510 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
30520 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  stmt*,int,const 
30530 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a  char*,int,void(*
30540 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
30550 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
30560 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
30570 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
30580 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
30590 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
305a0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
305b0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
305c0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
305d0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
305e0 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
305f0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
30600 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
30610 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
30620 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ng);.int sqlite3
30630 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
30640 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
30650 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
30660 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
30670 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
30680 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30690 6e 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  nt, void*, const
306a0 20 63 68 61 72 2a 2c 76 6f 69 64 28 2a 29 28 76   char*,void(*)(v
306b0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
306c0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
306d0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
306e0 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e   int, int n);.in
306f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
30700 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  eroblob64(sqlite
30710 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
30720 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a  lite3_uint64);..
30730 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30740 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
30750 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48  rameters.** METH
30760 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
30770 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
30780 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
30790 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
307a0 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
307b0 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
307c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
307d0 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
307e0 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
307f0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
30800 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
30810 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
30820 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
30830 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
30840 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
30850 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
30860 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
30870 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
30880 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
30890 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
308a0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
308b0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
308c0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
308d0 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
308e0 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
308f0 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
30900 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
30910 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
30920 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
30930 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
30940 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
30950 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
30960 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
30970 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
30980 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
30990 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
309a0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
309b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
309c0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
309d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
309e0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
309f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
30a00 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30a10 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
30a20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
30a30 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
30a40 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
30a50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
30a60 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
30a70 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f  rameter.** METHO
30a80 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30a90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30aa0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30ab0 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
30ac0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
30ad0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
30ae0 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
30af0 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
30b00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30b10 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
30b20 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
30b30 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
30b40 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
30b50 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
30b60 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
30b70 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
30b80 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
30b90 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
30ba0 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
30bb0 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
30bc0 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
30bd0 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
30be0 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
30bf0 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
30c00 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
30c10 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
30c20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
30c30 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
30c40 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
30c50 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
30c60 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
30c70 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
30c80 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
30c90 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
30ca0 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
30cb0 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
30cc0 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
30cd0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
30ce0 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
30cf0 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
30d00 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
30d10 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
30d20 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
30d30 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
30d40 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
30d50 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
30d60 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
30d70 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
30d80 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
30d90 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
30da0 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
30db0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
30dc0 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73 71  are16()],.** [sq
30dd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
30de0 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74  v2()], or [sqlit
30df0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28  e3_prepare16_v3(
30e00 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
30e10 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
30e20 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
30e30 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
30e40 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
30e50 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
30e60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
30e70 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
30e80 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  x()]..*/.const c
30e90 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
30ea0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
30eb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30ec0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
30ed0 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
30ee0 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
30ef0 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
30f00 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
30f10 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
30f20 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
30f30 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
30f40 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
30f50 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
30f60 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
30f70 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
30f80 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
30f90 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
30fa0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
30fb0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
30fc0 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
30fd0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
30fe0 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
30ff0 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
31000 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
31010 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
31020 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
31030 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
31040 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
31050 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
31060 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
31070 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
31080 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
31090 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
310a0 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a  epare16_v3()]..*
310b0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
310c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
310d0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
310e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
310f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
31100 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
31110 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
31120 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a  ameter_name()]..
31130 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
31140 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
31150 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
31160 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
31170 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
31180 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
31190 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
311a0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
311b0 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
311c0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
311d0 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
311e0 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
311f0 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
31200 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
31210 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
31220 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
31230 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
31240 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31250 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
31260 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
31270 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
31280 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
31290 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
312a0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
312b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
312c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
312d0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
312e0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
312f0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
31300 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
31310 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
31320 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
31330 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
31340 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
31350 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
31360 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68  atement]. ^If th
31370 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
31380 6e 73 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73  ns 0, that means
31390 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72   the .** [prepar
313a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65  ed statement] re
313b0 74 75 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66  turns no data (f
313c0 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
313d0 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77  PDATE])..** ^How
313e0 65 76 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75  ever, just becau
313f0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
31400 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69  returns a positi
31410 76 65 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e  ve number does n
31420 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  ot.** mean that 
31430 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73  one or more rows
31440 20 6f 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65   of data will be
31450 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53   returned.  ^A S
31460 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a  ELECT statement.
31470 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68  ** will always h
31480 61 76 65 20 61 20 70 6f 73 69 74 69 76 65 20 73  ave a positive s
31490 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
314a0 75 6e 74 28 29 20 62 75 74 20 64 65 70 65 6e 64  unt() but depend
314b0 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48  ing on the.** WH
314c0 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
314d0 72 61 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74  raints and the t
314e0 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74  able content, it
314f0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f   might return no
31500 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   rows..**.** See
31510 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
31520 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
31530 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
31540 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
31550 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
31560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31570 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
31580 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
31590 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
315a0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
315b0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
315c0 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
315d0 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
315e0 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
315f0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
31600 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
31610 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
31620 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
31630 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
31640 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
31650 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
31660 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
31670 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
31680 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
31690 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
316a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
316b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
316c0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
316d0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
316e0 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
316f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31700 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
31710 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
31720 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
31730 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
31740 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
31750 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
31760 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
31770 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
31780 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
31790 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
317a0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
317b0 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
317c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
317d0 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
317e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
317f0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
31800 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
31810 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
31820 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
31830 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
31840 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
31850 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
31860 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
31870 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
31880 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
31890 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
318a0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
318b0 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
318c0 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
318d0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
318e0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
318f0 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
31900 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
31910 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
31920 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
31930 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
31940 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
31950 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
31960 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
31970 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
31980 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
31990 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
319a0 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
319b0 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
319c0 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
319d0 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
319e0 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
319f0 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
31a00 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
31a10 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
31a20 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
31a30 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
31a40 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
31a50 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
31a60 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  e next..*/.const
31a70 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
31a80 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
31a90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
31aa0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
31ab0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
31ac0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
31ad0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
31ae0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
31af0 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
31b00 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
31b10 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
31b20 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
31b30 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
31b40 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
31b50 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
31b60 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
31b70 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
31b80 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
31b90 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
31ba0 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
31bb0 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
31bc0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
31bd0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
31be0 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
31bf0 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
31c00 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
31c10 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
31c20 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
31c30 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
31c40 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
31c50 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
31c60 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
31c70 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
31c80 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
31c90 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
31ca0 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
31cb0 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
31cc0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
31cd0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
31ce0 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
31cf0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
31d00 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
31d10 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
31d20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31d30 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
31d40 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
31d50 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
31d60 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
31d70 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
31d80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
31d90 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
31da0 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
31db0 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
31dc0 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
31dd0 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
31de0 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
31df0 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
31e00 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
31e10 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
31e20 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
31e30 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
31e40 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
31e50 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
31e60 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
31e70 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
31e80 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
31e90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31ea0 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
31eb0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
31ec0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
31ed0 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
31ee0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
31ef0 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
31f00 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
31f10 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
31f20 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
31f30 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
31f40 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
31f50 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
31f60 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
31f70 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
31f80 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
31f90 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
31fa0 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
31fb0 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
31fc0 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
31fd0 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
31fe0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
31ff0 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
32000 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
32010 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
32020 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
32030 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
32040 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
32050 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
32060 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
32070 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
32080 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
32090 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
320a0 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
320b0 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
320c0 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
320d0 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
320e0 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
320f0 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
32100 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
32110 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
32120 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
32130 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
32140 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
32150 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
32160 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
32170 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
32180 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
32190 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
321a0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
321b0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
321c0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
321d0 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
321e0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
321f0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
32200 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
32210 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
32220 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
32230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32240 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
32250 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
32260 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
32270 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
32280 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
32290 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
322a0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
322b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
322c0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
322d0 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
322e0 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
322f0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
32300 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32310 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
32320 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
32330 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
32340 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
32350 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
32360 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
32370 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
32380 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
32390 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
323a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
323b0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
323c0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
323d0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
323e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
323f0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
32400 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
32410 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
32420 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
32430 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
32440 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
32450 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
32460 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
32470 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
32480 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
32490 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
324a0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
324b0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
324c0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
324d0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
324e0 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
324f0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
32500 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
32510 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  tmt.**.** ^(The 
32520 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
32530 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
32540 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
32550 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
32560 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
32570 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
32580 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
32590 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
325a0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
325b0 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
325c0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
325d0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
325e0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
325f0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
32600 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
32610 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
32620 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
32630 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
32640 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
32650 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
32660 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
32670 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
32680 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
32690 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
326a0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
326b0 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
326c0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
326d0 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
326e0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
326f0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
32700 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
32710 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
32720 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
32730 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
32740 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
32750 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
32760 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
32770 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
32780 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
32790 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
327a0 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
327b0 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
327c0 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
327d0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
327e0 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
327f0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
32800 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
32810 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
32820 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
32830 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
32840 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
32850 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
32860 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
32870 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
32880 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
32890 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
328a0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
328b0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
328c0 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
328d0 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
328e0 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
328f0 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
32900 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
32910 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
32920 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
32930 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
32940 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
32950 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
32960 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
32970 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
32980 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
32990 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
329a0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
329b0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
329c0 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
329d0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
329e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
329f0 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
32a00 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  L Statement.** M
32a10 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
32a20 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  tmt.**.** After 
32a30 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
32a40 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
32a50 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 61  prepared using a
32a60 6e 79 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ny of.** [sqlite
32a70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
32a80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32a90 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v3()], [sqlite
32aa0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
32ab0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
32ac0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
32ad0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
32ae0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
32af0 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
32b00 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
32b10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
32b20 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
32b30 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
32b40 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
32b50 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
32b60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
32b70 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
32b80 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
32b90 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
32ba0 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
32bb0 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
32bc0 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
32bd0 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
32be0 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
32bf0 72 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65  r "vX" interface
32c00 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  s.** [sqlite3_pr
32c10 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71  epare_v3()], [sq
32c20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
32c30 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
32c40 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2c 0a 2a  epare16_v3()],.*
32c50 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
32c60 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
32c70 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
32c80 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
32c90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
32ca0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
32cb0 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
32cc0 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
32cd0 65 77 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  ew "vX" interfac
32ce0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
32cf0 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
32d00 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
32d10 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
32d20 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
32d30 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
32d40 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
32d50 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
32d60 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
32d70 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
32d80 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
32d90 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
32da0 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
32db0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
32dc0 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
32dd0 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
32de0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
32df0 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
32e00 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
32e10 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
32e20 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
32e30 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
32e40 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
32e50 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
32e60 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
32e70 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
32e80 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
32e90 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
32ea0 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
32eb0 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
32ec0 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
32ed0 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
32ee0 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
32ef0 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
32f00 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
32f10 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
32f20 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
32f30 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
32f40 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
32f50 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
32f60 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
32f70 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
32f80 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
32f90 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
32fa0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
32fb0 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
32fc0 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
32fd0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
32fe0 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
32ff0 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
33000 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
33010 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
33020 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
33030 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
33040 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
33050 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
33060 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
33070 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
33080 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
33090 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
330a0 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
330b0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
330c0 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
330d0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
330e0 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
330f0 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
33100 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
33110 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
33120 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
33130 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
33140 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
33150 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
33160 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
33170 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
33180 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
33190 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
331a0 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
331b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
331c0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
331d0 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
331e0 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
331f0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
33200 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
33210 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
33220 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
33230 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
33240 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
33250 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
33260 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
33270 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
33280 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
33290 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
332a0 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
332b0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
332c0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
332d0 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
332e0 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
332f0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
33300 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
33310 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
33320 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
33330 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
33340 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
33350 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
33360 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
33370 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
33380 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
33390 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
333a0 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
333b0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
333c0 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
333d0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
333e0 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
333f0 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
33400 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
33410 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
33420 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
33430 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
33440 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
33450 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
33460 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
33470 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
33480 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
33490 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
334a0 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
334b0 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
334c0 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
334d0 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
334e0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
334f0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
33500 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
33510 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
33520 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
33530 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
33540 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
33550 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
33560 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
33570 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
33580 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
33590 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
335a0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
335b0 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
335c0 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
335d0 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
335e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
335f0 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
33600 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
33610 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
33620 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
33630 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
33640 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
33650 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
33660 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
33670 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
33680 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
33690 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
336a0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
336b0 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
336c0 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
336d0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
336e0 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
336f0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
33700 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20   after [version 
33710 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65  3.6.23.1] ([date
33720 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a  of:3.6.23.1],.**
33730 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
33740 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
33750 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33760 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
33770 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
33780 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
33790 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
337a0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
337b0 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
337c0 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
337d0 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
337e0 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
337f0 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
33800 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
33810 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
33820 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
33830 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
33840 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
33850 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
33860 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
33870 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
33880 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
33890 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
338a0 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
338b0 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
338c0 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
338d0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
338e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
338f0 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
33900 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
33910 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
33920 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
33930 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
33940 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
33950 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
33960 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
33970 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
33980 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
33990 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
339a0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
339b0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
339c0 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
339d0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
339e0 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
339f0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
33a00 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
33a10 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
33a20 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
33a30 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
33a40 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
33a50 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
33a60 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
33a70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
33a80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
33a90 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
33aa0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f  _prepare_v3()] o
33ab0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
33ac0 72 65 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b  re_v2()].** or [
33ad0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
33ae0 36 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  6_v2()] or [sqli
33af0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
33b00 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
33b10 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
33b20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
33b30 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
33b40 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
33b50 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
33b60 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
33b70 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
33b80 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
33b90 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
33ba0 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
33bb0 75 73 65 20 6f 66 20 74 68 65 20 22 76 58 22 20  use of the "vX" 
33bc0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 72 65  interfaces is re
33bd0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e  commended..*/.in
33be0 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
33bf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
33c00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33c10 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
33c20 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
33c30 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
33c40 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
33c50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
33c60 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
33c70 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
33c80 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
33c90 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
33ca0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
33cb0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
33cc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33cd0 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
33ce0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
33cf0 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
33d00 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
33d10 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
33d20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
33d30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
33d40 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
33d50 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
33d60 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
33d70 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
33d80 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
33d90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
33da0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
33db0 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
33dc0 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
33dd0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
33de0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
33df0 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
33e00 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
33e10 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
33e20 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
33e30 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
33e40 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
33e50 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
33e60 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
33e70 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
33e80 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
33e90 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
33ea0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
33eb0 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
33ec0 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
33ed0 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
33ee0 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
33ef0 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
33f00 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
33f10 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
33f20 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
33f30 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
33f40 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
33f50 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
33f60 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
33f70 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
33f80 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
33f90 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
33fa0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
33fb0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
33fc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
33fd0 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
33fe0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
33ff0 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
34000 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
34010 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
34020 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
34030 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
34040 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
34050 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
34060 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
34070 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
34080 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
34090 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
340a0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
340b0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
340c0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
340d0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
340e0 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
340f0 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
34100 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
34110 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
34120 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
34130 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
34140 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
34150 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
34160 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
34170 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
34180 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
34190 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
341a0 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
341b0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
341c0 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
341d0 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
341e0 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
341f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
34200 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
34210 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
34220 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
34230 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
34240 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
34250 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
34260 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
34270 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
34280 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
34290 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
342a0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
342b0 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
342c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
342d0 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
342e0 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
342f0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
34300 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
34310 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  s}.** METHOD: sq
34320 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
34330 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62 3e   <b>Summary:</b>
34340 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
34350 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 30 20  <table border=0 
34360 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30 20 63 65  cellpadding=0 ce
34370 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a 20  llspacing=0>.** 
34380 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
34390 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f  e3_column_blob</
343a0 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
343b0 42 4c 4f 42 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  BLOB result.** <
343c0 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
343d0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 3c  3_column_double<
343e0 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
343f0 3e 52 45 41 4c 20 72 65 73 75 6c 74 0a 2a 2a 20  >REAL result.** 
34400 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
34410 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f 62  e3_column_int</b
34420 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 33  ><td>&rarr;<td>3
34430 32 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65  2-bit INTEGER re
34440 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
34450 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
34460 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e 26  n_int64</b><td>&
34470 72 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74 20  rarr;<td>64-bit 
34480 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a  INTEGER result.*
34490 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
344a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
344b0 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
344c0 64 3e 55 54 46 2d 38 20 54 45 58 54 20 72 65 73  d>UTF-8 TEXT res
344d0 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
344e0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
344f0 5f 74 65 78 74 31 36 3c 2f 62 3e 3c 74 64 3e 26  _text16</b><td>&
34500 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 31 36 20  rarr;<td>UTF-16 
34510 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  TEXT result.** <
34520 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
34530 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 3c 2f  3_column_value</
34540 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
34550 54 68 65 20 72 65 73 75 6c 74 20 61 73 20 61 6e  The result as an
34560 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
34570 6c 75 65 7c 75 6e 70 72 6f 74 65 63 74 65 64 20  lue|unprotected 
34580 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
34590 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  bject..** <tr><t
345a0 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73  d>&nbsp;<td>&nbs
345b0 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a 20  p;<td>&nbsp;.** 
345c0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
345d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 3c  e3_column_bytes<
345e0 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
345f0 3e 53 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 0a  >Size of a BLOB.
34600 2a 2a 20 6f 72 20 61 20 55 54 46 2d 38 20 54 45  ** or a UTF-8 TE
34610 58 54 20 72 65 73 75 6c 74 20 69 6e 20 62 79 74  XT result in byt
34620 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  es.** <tr><td><b
34630 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
34640 62 79 74 65 73 31 36 26 6e 62 73 70 3b 26 6e 62  bytes16&nbsp;&nb
34650 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64 3e 26  sp;</b>.** <td>&
34660 72 61 72 72 3b 26 6e 62 73 70 3b 26 6e 62 73 70  rarr;&nbsp;&nbsp
34670 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 55 54 46  ;<td>Size of UTF
34680 2d 31 36 0a 2a 2a 20 54 45 58 54 20 69 6e 20 62  -16.** TEXT in b
34690 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ytes.** <tr><td>
346a0 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
346b0 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74 64 3e 26 72  n_type</b><td>&r
346c0 61 72 72 3b 3c 74 64 3e 44 65 66 61 75 6c 74 0a  arr;<td>Default.
346d0 2a 2a 20 64 61 74 61 74 79 70 65 20 6f 66 20 74  ** datatype of t
346e0 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 2f 74  he result.** </t
346f0 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  able></blockquot
34700 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 74 61  e>.**.** <b>Deta
34710 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e  ils:</b>.**.** ^
34720 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
34730 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
34740 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
34750 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
34760 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
34770 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
34780 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
34790 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
347a0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
347b0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
347c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
347d0 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
347e0 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
347f0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
34800 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
34810 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
34820 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
34830 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
34840 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
34850 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
34860 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
34870 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
34880 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
34890 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
348a0 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
348b0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
348c0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
348d0 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
348e0 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
348f0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
34900 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
34910 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
34920 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
34930 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
34940 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
34950 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
34960 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
34970 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
34980 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
34990 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
349a0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
349b0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
349c0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
349d0 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
349e0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
349f0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
34a00 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
34a10 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
34a20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
34a30 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
34a40 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
34a50 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
34a60 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
34a70 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
34a80 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
34a90 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
34aa0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
34ab0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
34ac0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
34ad0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
34ae0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
34af0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
34b00 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
34b10 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
34b20 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
34b30 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
34b40 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
34b50 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
34b60 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
34b70 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
34b80 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
34b90 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
34ba0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
34bb0 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
34bc0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
34bd0 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
34be0 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
34bf0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
34c00 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
34c10 20 66 69 72 73 74 20 73 69 78 20 69 6e 74 65 72   first six inter
34c20 66 61 63 65 73 20 28 5f 62 6c 6f 62 2c 20 5f 64  faces (_blob, _d
34c30 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f 69 6e  ouble, _int, _in
34c40 74 36 34 2c 20 5f 74 65 78 74 2c 20 61 6e 64 20  t64, _text, and 
34c50 5f 74 65 78 74 31 36 29 0a 2a 2a 20 65 61 63 68  _text16).** each
34c60 20 72 65 74 75 72 6e 20 74 68 65 20 76 61 6c 75   return the valu
34c70 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
34c80 6c 75 6d 6e 20 69 6e 20 61 20 73 70 65 63 69 66  lumn in a specif
34c90 69 63 20 64 61 74 61 20 66 6f 72 6d 61 74 2e 20  ic data format. 
34ca0 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c   If.** the resul
34cb0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74 20  t column is not 
34cc0 69 6e 69 74 69 61 6c 6c 79 20 69 6e 20 74 68 65  initially in the
34cd0 20 72 65 71 75 65 73 74 65 64 20 66 6f 72 6d 61   requested forma
34ce0 74 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  t (for example,.
34cf0 2a 2a 20 69 66 20 74 68 65 20 71 75 65 72 79 20  ** if the query 
34d00 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
34d10 65 72 20 62 75 74 20 74 68 65 20 73 71 6c 69 74  er but the sqlit
34d20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
34d30 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
34d40 20 75 73 65 64 20 74 6f 20 65 78 74 72 61 63 74   used to extract
34d50 20 74 68 65 20 76 61 6c 75 65 29 20 74 68 65 6e   the value) then
34d60 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 74 79   an automatic ty
34d70 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  pe conversion is
34d80 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a   performed..**.*
34d90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
34da0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
34db0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
34dc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
34dd0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
34de0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
34df0 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
34e00 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
34e10 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
34e20 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
34e30 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
34e40 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
34e50 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
34e60 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
34e70 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
34e80 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54  LITE_NULL]..** T
34e90 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
34ea0 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
34eb0 6e 5f 74 79 70 65 28 29 20 63 61 6e 20 62 65 20  n_type() can be 
34ec0 75 73 65 64 20 74 6f 20 64 65 63 69 64 65 20 77  used to decide w
34ed0 68 69 63 68 0a 2a 2a 20 6f 66 20 74 68 65 20 66  hich.** of the f
34ee0 69 72 73 74 20 73 69 78 20 69 6e 74 65 72 66 61  irst six interfa
34ef0 63 65 20 73 68 6f 75 6c 64 20 62 65 20 75 73 65  ce should be use
34f00 64 20 74 6f 20 65 78 74 72 61 63 74 20 74 68 65  d to extract the
34f10 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a   column value..*
34f20 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65 74 75  * The value retu
34f30 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
34f40 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
34f50 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
34f60 20 69 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f 6d 61   if no.** automa
34f70 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73  tic type convers
34f80 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
34f90 65 64 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ed for the value
34fa0 20 69 6e 20 71 75 65 73 74 69 6f 6e 2e 20 20 0a   in question.  .
34fb0 2a 2a 20 41 66 74 65 72 20 61 20 74 79 70 65 20  ** After a type 
34fc0 63 6f 6e 76 65 72 73 69 6f 6e 2c 20 74 68 65 20  conversion, the 
34fd0 72 65 73 75 6c 74 20 6f 66 20 63 61 6c 6c 69 6e  result of callin
34fe0 67 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  g sqlite3_column
34ff0 5f 74 79 70 65 28 29 0a 2a 2a 20 69 73 20 75 6e  _type().** is un
35000 64 65 66 69 6e 65 64 2c 20 74 68 6f 75 67 68 20  defined, though 
35010 68 61 72 6d 6c 65 73 73 2e 20 20 46 75 74 75 72  harmless.  Futur
35020 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
35030 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
35040 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
35050 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
35060 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
35070 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
35080 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  version..**.** I
35090 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
350a0 61 20 42 4c 4f 42 20 6f 72 20 61 20 54 45 58 54  a BLOB or a TEXT
350b0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 74 68   string, then th
350c0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
350d0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 6f 72 20 73  _bytes().** or s
350e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
350f0 74 65 73 31 36 28 29 20 69 6e 74 65 72 66 61 63  tes16() interfac
35100 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
35110 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
35120 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 61 74 20  size.** of that 
35130 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
35140 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
35150 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
35160 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
35170 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
35180 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
35190 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
351a0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
351b0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
351c0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
351d0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
351e0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
351f0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
35200 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
35210 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
35220 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
35230 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
35240 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
35250 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
35260 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
35270 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
35280 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35290 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
352a0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
352b0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
352c0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
352d0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
352e0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
352f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
35300 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
35310 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
35320 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
35330 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35340 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
35350 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
35360 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
35370 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
35380 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
35390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
353a0 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
353b0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
353c0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
353d0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
353e0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
353f0 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
35400 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
35410 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35420 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
35430 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
35440 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
35450 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
35460 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
35470 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
35480 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
35490 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
354a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
354b0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
354c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
354d0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
354e0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
354f0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
35500 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
35510 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
35520 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
35530 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
35540 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
35550 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
35560 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
35570 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
35580 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
35590 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
355a0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
355b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
355c0 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
355d0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
355e0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
355f0 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
35600 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
35610 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
35620 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
35630 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
35640 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
35650 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
35660 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
35670 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
35680 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
35690 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
356a0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
356b0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
356c0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
356d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
356e0 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
356f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
35700 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
35710 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
35720 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
35730 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
35740 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
35750 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
35760 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
35770 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
35780 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
35790 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69  ..**.** <b>Warni
357a0 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a  ng:</b> ^The obj
357b0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
357c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
357d0 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
357e0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
357f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
35800 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74  ject.  In a mult
35810 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f  ithreaded enviro
35820 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70  nment,.** an unp
35830 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
35840 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
35850 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73  y only be used s
35860 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73  afely with.** [s
35870 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
35880 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
35890 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
358a0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
358b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
358c0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
358d0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
358e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
358f0 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
35900 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
35910 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
35920 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
35930 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
35940 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
35950 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
35960 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
35970 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
35980 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  )], the behavior
35990 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
359a0 66 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 74 68  fe..** Hence, th
359b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
359c0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
359d0 63 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61 6c 6c  ce.** is normall
359e0 79 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 77 69  y only useful wi
359f0 74 68 69 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65  thin the impleme
35a00 6e 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20 5b  ntation of .** [
35a10 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35a20 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
35a30 73 5d 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74  s] or [virtual t
35a40 61 62 6c 65 73 5d 2c 20 6e 6f 74 20 77 69 74 68  ables], not with
35a50 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  in.** top-level 
35a60 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
35a70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 65 73  ..**.** The thes
35a80 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 61  e routines may a
35a90 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
35aa0 74 20 74 68 65 20 64 61 74 61 74 79 70 65 20 6f  t the datatype o
35ab0 66 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a  f the result..**
35ac0 20 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69   ^For example, i
35ad0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
35ae0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
35af0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
35b00 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
35b10 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
35b20 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
35b30 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
35b40 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
35b50 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
35b60 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
35b70 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
35b80 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
35b90 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
35ba0 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
35bb0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
35bc0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
35bd0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
35be0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
35bf0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
35c00 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
35c10 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
35c20 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
35c30 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
35c40 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
35c50 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
35c60 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
35c70 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
35c80 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
35c90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
35ca0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
35cb0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
35cc0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
35cd0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
35ce0 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
35cf0 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
35d00 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
35d10 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
35d20 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
35d30 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
35d40 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
35d50 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
35d60 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
35d70 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
35d80 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
35d90 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
35da0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
35db0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
35dc0 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
35dd0 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
35de0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
35df0 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
35e00 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
35e10 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
35e20 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
35e30 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
35e40 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
35e50 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
35e60 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
35e70 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
35e80 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  OB    <td> [CAST
35e90 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72  ] to BLOB.** <tr
35ea0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
35eb0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
35ec0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
35ed0 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
35ee0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
35ef0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
35f00 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
35f10 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
35f20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
35f30 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
35f40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
35f50 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
35f60 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
35f70 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
35f80 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
35f90 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
35fa0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
35fb0 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
35fc0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
35fd0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
35fe0 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
35ff0 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
36000 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
36010 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
36020 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
36030 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
36040 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
36050 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
36060 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
36070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
36080 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
36090 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
360a0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
360b0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
360c0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
360d0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
360e0 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
360f0 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
36100 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
36110 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
36120 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
36130 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
36140 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
36150 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and 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 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
36180 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
36190 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
361a0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
361b0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
361c0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
361d0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
361e0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
361f0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
36200 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
36210 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
36220 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
36230 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
36240 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
36250 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
36260 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
36270 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
36280 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
36290 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
362a0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
362b0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
362c0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
362d0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
362e0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
362f0 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
36300 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
36310 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
36320 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
36330 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
36340 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
36350 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
36360 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
36370 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
36380 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
36390 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
363a0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
363b0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
363c0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
363d0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
363e0 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
363f0 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
36400 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
36410 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
36420 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
36430 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
36440 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
36450 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
36460 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
36470 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
36480 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
36490 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
364a0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
364b0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
364c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
364d0 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
364e0 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
364f0 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
36500 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
36510 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
36520 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
36530 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
36540 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
36550 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
36560 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
36570 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
36580 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
36590 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
365a0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
365b0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
365c0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
365d0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
365e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
365f0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
36600 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
36610 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
36620 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
36630 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
36640 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
36650 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
36660 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
36670 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
36680 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
36690 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
366a0 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
366b0 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
366c0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
366d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
366e0 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
366f0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
36700 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
36710 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
36720 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36730 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
36740 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
36750 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
36760 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36770 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
36780 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
36790 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
367a0 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
367b0 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
367c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
367d0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
367e0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
367f0 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
36800 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
36810 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
36820 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
36830 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
36840 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
36850 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
36860 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
36870 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
36880 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
36890 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
368a0 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
368b0 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
368c0 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
368d0 79 2e 20 20 44 6f 20 6e 6f 74 20 70 61 73 73 20  y.  Do not pass 
368e0 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
368f0 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
36900 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
36910 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
36920 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
36930 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
36940 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
36950 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f  *.** ^(If a memo
36960 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
36970 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
36980 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
36990 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
369a0 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
369b0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
369c0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
369d0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
369e0 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
369f0 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
36a00 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
36a10 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
36a20 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
36a30 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
36a40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
36a50 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
36a60 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
36a70 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73  OMEM].)^.*/.cons
36a80 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
36a90 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
36aa0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36ab0 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
36ac0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
36ad0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
36ae0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
36af0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36b00 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
36b10 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
36b20 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
36b30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
36b40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36b50 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
36b60 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
36b70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36b80 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
36b90 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
36ba0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
36bb0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
36bc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36bd0 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
36be0 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
36bf0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
36c00 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
36c10 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
36c20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
36c30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36c40 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
36c50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36c60 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
36c70 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36c80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
36c90 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
36ca0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
36cb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36cc0 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
36cd0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
36ce0 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55  Object.** DESTRU
36cf0 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
36d00 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
36d10 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
36d20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
36d30 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
36d40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36d50 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
36d60 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
36d70 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
36d80 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
36d90 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
36da0 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
36db0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
36dc0 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
36dd0 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
36de0 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
36df0 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
36e00 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
36e10 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
36e20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
36e30 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
36e40 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
36e50 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
36e60 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
36e70 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
36e80 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
36e90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36ea0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
36eb0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
36ec0 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
36ed0 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
36ee0 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
36ef0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36f00 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
36f10 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
36f20 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
36f30 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
36f40 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
36f50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
36f60 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
36f70 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
36f80 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
36f90 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
36fa0 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
36fb0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
36fc0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
36fd0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
36fe0 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
36ff0 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
37000 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
37010 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
37020 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
37030 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
37040 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
37050 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
37060 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
37070 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
37080 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
37090 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
370a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
370b0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
370c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
370d0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
370e0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
370f0 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
37100 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
37110 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
37120 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
37130 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
37140 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
37150 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
37160 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
37170 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
37180 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74  rruption..*/.int
37190 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
371a0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
371b0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
371c0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
371d0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
371e0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45  ent Object.** ME
371f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
37200 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  mt.**.** The sql
37210 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
37220 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
37230 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
37240 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
37250 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
37260 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
37270 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
37280 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
37290 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
372a0 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
372b0 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
372c0 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
372d0 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
372e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
372f0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
37300 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
37310 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
37320 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
37330 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
37340 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
37350 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
37360 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
37370 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
37380 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
37390 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
373a0 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
373b0 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
373c0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
373d0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
373e0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
373f0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
37400 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
37410 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
37420 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
37430 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
37440 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
37450 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
37460 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
37470 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
37480 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
37490 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
374a0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
374b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
374c0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
374d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
374e0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
374f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
37500 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
37510 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
37520 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
37530 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
37540 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
37550 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
37560 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
37570 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
37580 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
37590 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
375a0 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
375b0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
375c0 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
375d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
375e0 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
375f0 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
37600 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
37610 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37620 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
37630 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
37640 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
37650 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
37660 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
37670 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
37680 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
37690 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
376a0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
376b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
376c0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
376d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
376e0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
376f0 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
37700 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
37710 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
37720 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
37730 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
37740 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
37750 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
37760 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
37770 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
37780 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
37790 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
377a0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
377b0 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
377c0 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
377d0 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
377e0 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
377f0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
37800 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
37810 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
37820 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
37830 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
37840 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
37850 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
37860 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
37870 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
37880 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
37890 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
378a0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
378b0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
378c0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
378d0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
378e0 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
378f0 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
37900 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
37910 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
37920 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
37930 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
37940 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
37950 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
37960 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
37970 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
37980 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
37990 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
379a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
379b0 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
379c0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
379d0 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
379e0 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
379f0 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
37a00 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
37a10 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
37a20 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
37a30 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
37a40 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
37a50 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
37a60 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
37a70 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
37a80 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
37a90 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
37aa0 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
37ab0 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
37ac0 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
37ad0 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
37ae0 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
37af0 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
37b00 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
37b10 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
37b20 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
37b30 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
37b40 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
37b50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
37b60 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
37b70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
37b80 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
37b90 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
37ba0 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
37bb0 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
37bc0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
37bd0 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
37be0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
37bf0 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
37c00 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
37c10 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
37c20 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
37c30 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
37c40 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
37c50 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
37c60 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
37c70 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
37c80 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
37c90 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
37ca0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
37cb0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
37cc0 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
37cd0 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
37ce0 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
37cf0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
37d00 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
37d10 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
37d20 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
37d30 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
37d40 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20  should set this 
37d50 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
37d60 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
37d70 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   if the function
37d80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37d90 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c  invokes .** [sql
37da0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
37db0 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6le()] on an inp
37dc0 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ut, or [SQLITE_U
37dd0 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a  TF16BE] if the.*
37de0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
37df0 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65   invokes [sqlite
37e00 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
37e10 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
37e20 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   or.** [SQLITE_U
37e30 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65  TF16] if [sqlite
37e40 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
37e50 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53  ] is used, or [S
37e60 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f  QLITE_UTF8].** o
37e70 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20  therwise.  ^The 
37e80 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
37e90 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
37ea0 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
37eb0 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66  es using.** diff
37ec0 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20  erent preferred 
37ed0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20  text encodings, 
37ee0 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69  with different i
37ef0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
37f00 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64  or.** each encod
37f10 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  ing..** ^When mu
37f20 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
37f30 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
37f40 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
37f50 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
37f60 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
37f70 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
37f80 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
37f90 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
37fa0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
37fb0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
37fc0 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e  meter may option
37fd0 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74  ally be ORed wit
37fe0 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  h [SQLITE_DETERM
37ff0 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73  INISTIC].** to s
38000 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66  ignal that the f
38010 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77  unction will alw
38020 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
38030 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e  ame result given
38040 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70  .** the same inp
38050 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e  uts within a sin
38060 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
38070 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e  t.  Most SQL fun
38080 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65  ctions are.** de
38090 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
380a0 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64  e built-in [rand
380b0 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  om()] SQL functi
380c0 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  on is an example
380d0 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   of a.** functio
380e0 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65  n that is not de
380f0 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
38100 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70  e SQLite query p
38110 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74  lanner is able t
38120 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64  o.** perform add
38130 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61  itional optimiza
38140 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69  tions on determi
38150 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nistic functions
38160 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74  , so use.** of t
38170 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  he [SQLITE_DETER
38180 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69  MINISTIC] flag i
38190 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68  s recommended wh
381a0 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a  ere possible..**
381b0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
381c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
381d0 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
381e0 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
381f0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
38200 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
38210 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
38220 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
38230 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
38240 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
38250 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
38260 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
38270 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
38280 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
38290 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
382a0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
382b0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
382c0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
382d0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
382e0 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
382f0 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
38300 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
38310 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
38320 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
38330 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
38340 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
38350 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
38360 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
38370 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
38380 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
38390 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
383a0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
383b0 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
383c0 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
383d0 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
383e0 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
383f0 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
38400 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
38410 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
38420 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
38430 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
38440 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
38450 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
38460 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
38470 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
38480 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
38490 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
384a0 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
384b0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
384c0 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
384d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
384e0 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
384f0 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
38500 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
38510 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
38520 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
38530 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
38540 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
38550 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
38560 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
38570 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
38580 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
38590 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
385a0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
385b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
385c0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
385d0 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
385e0 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
385f0 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
38600 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
38610 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
38620 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
38630 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
38640 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
38650 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
38660 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
38670 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
38680 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
38690 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
386a0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
386b0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
386c0 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
386d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
386e0 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
386f0 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
38700 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
38710 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
38720 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
38730 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
38740 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
38750 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
38760 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
38770 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
38780 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
38790 20 6d 6f 73 74 20 63 6