/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 68bfa4942af031d16055ab4d37d26fe44b11b0756a89f309cd98ea17080db1cc:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
5180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5190: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
51c0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
51d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
5240: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
5280: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
53e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53f0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
5400: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5410: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
5420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5430: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5440: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5450: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5470: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5480: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5490: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
54a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54b0: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
54c0: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
54d0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
54e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54f0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
5500: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5510: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
5520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5530: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5540: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5550: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5570: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5580: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5590: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55b0: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55d0: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
55e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55f0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
5600: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5610: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
5620: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5630: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
5640: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5650: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5670: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
5680: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5690: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
56a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56b0: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
56c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
56d0: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
56e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
56f0: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20  RR_DELETE_NOENT 
5700: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5710: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64  RR | (23<<8)).#d
5720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5730: 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20  RR_MMAP         
5740: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5750: 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64  RR | (24<<8)).#d
5760: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5770: 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20  RR_GETTEMPPATH  
5780: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5790: 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64  RR | (25<<8)).#d
57a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57b0: 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  RR_CONVPATH     
57c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
57d0: 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64  RR | (26<<8)).#d
57e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
57f0: 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20  RR_VNODE        
5800: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5810: 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64  RR | (27<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5830: 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 20 20  RR_AUTH         
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5850: 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64  RR | (28<<8)).#d
5860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5870: 52 52 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20  RR_BEGIN_ATOMIC 
5880: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5890: 52 52 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64  RR | (29<<8)).#d
58a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58b0: 52 52 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  RR_COMMIT_ATOMIC
58c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
58d0: 52 52 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64  RR | (30<<8)).#d
58e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
58f0: 52 52 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  RR_ROLLBACK_ATOM
5900: 49 43 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45  IC   (SQLITE_IOE
5910: 52 52 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64  RR | (31<<8)).#d
5920: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5930: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
5940: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
5950: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
5960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5970: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
5980: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5990: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
59a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
59b0: 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20  USY_SNAPSHOT    
59c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
59d0: 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29  USY   |  (2<<8))
59e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59f0: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5a00: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
5a10: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
5a20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a30: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52  E_CANTOPEN_ISDIR
5a40: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5a50: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c  E_CANTOPEN | (2<
5a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a70: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c  ITE_CANTOPEN_FUL
5a80: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  LPATH       (SQL
5a90: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5aa0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5ab0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43  QLITE_CANTOPEN_C
5ac0: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53  ONVPATH       (S
5ad0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5ae0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5af0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f   SQLITE_CORRUPT_
5b00: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20  VTAB            
5b10: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20  (SQLITE_CORRUPT 
5b20: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5b30: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5b40: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
5b50: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5b60: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  Y | (1<<8)).#def
5b70: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5b80: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20  NLY_CANTLOCK    
5b90: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5ba0: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  NLY | (2<<8)).#d
5bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5bc0: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20  DONLY_ROLLBACK  
5bd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5be0: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a  DONLY | (3<<8)).
5bf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5c00: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20  EADONLY_DBMOVED 
5c10: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5c20: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29  EADONLY | (4<<8)
5c30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c40: 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20  _ABORT_ROLLBACK 
5c50: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5c60: 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29  _ABORT | (2<<8))
5c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c80: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b  CONSTRAINT_CHECK
5c90: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ca0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c  CONSTRAINT | (1<
5cb0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5cc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5cd0: 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c  OMMITHOOK   (SQL
5ce0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5cf0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5d00: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5d10: 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20  NT_FOREIGNKEY   
5d20: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5d30: 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  NT | (3<<8)).#de
5d40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5d50: 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20  TRAINT_FUNCTION 
5d60: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5d70: 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29  TRAINT | (4<<8))
5d80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d90: 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55  CONSTRAINT_NOTNU
5da0: 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  LL      (SQLITE_
5db0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c  CONSTRAINT | (5<
5dc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5dd0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50  ITE_CONSTRAINT_P
5de0: 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c  RIMARYKEY   (SQL
5df0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5e00: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
5e10: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5e20: 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  NT_TRIGGER      
5e30: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5e40: 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  NT | (7<<8)).#de
5e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5e60: 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20  TRAINT_UNIQUE   
5e70: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5e80: 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29  TRAINT | (8<<8))
5e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ea0: 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20  CONSTRAINT_VTAB 
5eb0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ec0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c  CONSTRAINT | (9<
5ed0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5ee0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52  ITE_CONSTRAINT_R
5ef0: 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c  OWID        (SQL
5f00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5f10: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
5f20: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5f30: 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20  ECOVER_WAL      
5f40: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5f50: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5f60: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52   SQLITE_NOTICE_R
5f70: 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20  ECOVER_ROLLBACK 
5f80: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c  (SQLITE_NOTICE |
5f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5fa0: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f   SQLITE_WARNING_
5fb0: 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20  AUTOINDEX       
5fc0: 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20  (SQLITE_WARNING 
5fd0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5fe0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53  e SQLITE_AUTH_US
5ff0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ER              
6000: 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20   (SQLITE_AUTH | 
6010: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
6020: 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50  SQLITE_OK_LOAD_P
6030: 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28  ERMANENTLY     (
6040: 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c  SQLITE_OK | (1<<
6050: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
6060: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
6070: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
6080: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
6090: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
60a0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
60b0: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
60c0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
60d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
60e0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
60f0: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
6100: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
6110: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
6120: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23  en] method..*/.#
6130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6140: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
6150: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20      0x00000001  
6160: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6170: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6180: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6190: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
61a0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20      0x00000002  
61b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
61c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
61d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
61e0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
61f0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20      0x00000004  
6200: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6210: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6230: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
6240: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20      0x00000008  
6250: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6270: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
6280: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20      0x00000010  
6290: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
62a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62b0: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20  EN_AUTOPROXY    
62c0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20      0x00000020  
62d0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
62e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62f0: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  EN_URI          
6300: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20      0x00000040  
6310: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6320: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6340: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20  EN_MEMORY       
6350: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20      0x00000080  
6360: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6370: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6390: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
63a0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20      0x00000100  
63b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
63c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
63d0: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
63e0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20      0x00000200  
63f0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6410: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
6420: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20      0x00000400  
6430: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6440: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6450: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
6460: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20      0x00000800  
6470: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6480: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6490: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
64a0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20      0x00001000  
64b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
64c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
64d0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
64e0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20      0x00002000  
64f0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6510: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
6520: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20  L   0x00004000  
6530: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6540: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6550: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
6560: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20      0x00008000  
6570: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6580: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
65a0: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
65b0: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20      0x00010000  
65c0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
65d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
65e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
65f0: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  EN_SHAREDCACHE  
6600: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20      0x00020000  
6610: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6620: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6630: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6640: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
6650: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20      0x00040000  
6660: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6670: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6680: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6690: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  EN_WAL          
66a0: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20      0x00080000  
66b0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a  /* VFS only */..
66c0: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20  /* Reserved:    
66d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
66e0: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20       0x00F00000 
66f0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
6700: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
6710: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  cteristics.**.**
6720: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
6730: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
6740: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
6750: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
6760: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
6770: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
6780: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
6790: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
67a0: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
67b0: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
67c0: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
67d0: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
67e0: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
67f0: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
6800: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6810: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
6820: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
6830: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6840: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6850: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
6860: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
6870: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6880: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6890: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
68a0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
68b0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
68c0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
68d0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
68e0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
68f0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
6900: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
6910: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
6920: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6940: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
6950: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
6960: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6970: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
6980: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
6990: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
69a0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
69b0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
69c0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
69d0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
69e0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
69f0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
6a00: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6a10: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
6a20: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
6a30: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
6a40: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
6a50: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20  * to xWrite().  
6a60: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6a70: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6a80: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65  RITE property me
6a90: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65  ans that.** afte
6aa0: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69  r reboot followi
6ab0: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f  ng a crash or po
6ac0: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e  wer loss, the on
6ad0: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a  ly bytes in a.**
6ae0: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20   file that were 
6af0: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61  written at the a
6b00: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c  pplication level
6b10: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e   might have chan
6b20: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ged.** and that 
6b30: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20  adjacent bytes, 
6b40: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69  even bytes withi
6b50: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f  n the same secto
6b60: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74  r are.** guarant
6b70: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e  eed to be unchan
6b80: 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ged.  The SQLITE
6b90: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6ba0: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20  LE_WHEN_OPEN.** 
6bb0: 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74  flag indicates t
6bc0: 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f  hat a file canno
6bd0: 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65  t be deleted whe
6be0: 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20  n open.  The.** 
6bf0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6c00: 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69  UTABLE flag indi
6c10: 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66  cates that the f
6c20: 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61  ile is on.** rea
6c30: 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64  d-only media and
6c40: 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
6c50: 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65  ed even by proce
6c60: 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65  sses with.** ele
6c70: 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73  vated privileges
6c80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
6c90: 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41  TE_IOCAP_BATCH_A
6ca0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6cb0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 75 6e  eans that the un
6cc0: 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66 69 6c 65  derlying.** file
6cd0: 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20  system supports 
6ce0: 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c 65 20 77  doing multiple w
6cf0: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
6d00: 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68 65 6e 20  atomically when 
6d10: 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74 65 20 6f  those.** write o
6d20: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 62 72  perations are br
6d30: 61 63 6b 65 74 65 64 20 62 79 20 5b 53 51 4c 49  acketed by [SQLI
6d40: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
6d50: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 61 6e 64  TOMIC_WRITE] and
6d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
6d70: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
6d80: 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64 65 66 69  WRITE]..*/.#defi
6d90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6da0: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
6db0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6dc0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
6dd0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
6de0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6df0: 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65  00000002.#define
6e00: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6e10: 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20  OMIC1K          
6e20: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a       0x00000004.
6e30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6e40: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20  OCAP_ATOMIC2K   
6e50: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6e60: 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53  000008.#define S
6e70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6e80: 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC4K            
6e90: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
6ea0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6eb0: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
6ec0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6ed0: 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0020.#define SQL
6ee0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6ef0: 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  16K             
6f00: 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66   0x00000040.#def
6f10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6f20: 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20  _ATOMIC32K      
6f30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6f40: 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  80.#define SQLIT
6f50: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6f60: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
6f70: 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e  x00000100.#defin
6f80: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6f90: 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20  AFE_APPEND      
6fa0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
6fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6fc0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6fe0: 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20  0000400.#define 
6ff0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
7000: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
7010: 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23  EN  0x00000800.#
7020: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7030: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
7040: 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30  ERWRITE    0x000
7050: 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51  01000.#define SQ
7060: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
7070: 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  ABLE            
7080: 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 64 65    0x00002000.#de
7090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
70a0: 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 20 20  P_BATCH_ATOMIC  
70b0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 34           0x00004
70c0: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
70d0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
70e0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
70f0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
7100: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
7110: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
7120: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
7130: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
7140: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
7150: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
7160: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
7170: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7180: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
7190: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71a0: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
71b0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
71c0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
71d0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
71e0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
71f0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
7200: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7210: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
7220: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7230: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
7240: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
7250: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
7260: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
7270: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
7280: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
7290: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
72a0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
72b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
72c0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
72d0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
72e0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
72f0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
7300: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
7310: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
7320: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
7330: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
7340: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
7350: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
7360: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
7370: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
7380: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
7390: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
73a0: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
73b0: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
73c0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
73d0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
73e0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
73f0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
7400: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
7410: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
7420: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
7430: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
7440: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
7450: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
7460: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
7470: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
7480: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
7490: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
74a0: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
74b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
74c0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
74d0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
74e0: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
74f0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
7500: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
7510: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
7520: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
7530: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
7540: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
7550: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
7560: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
7570: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
7580: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
7590: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
75a0: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
75b0: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
75c0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
75d0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
75e0: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
75f0: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
7600: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
7610: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
7620: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
7630: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
7640: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
7650: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
7660: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
7670: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
7680: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
7690: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
76a0: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
76b0: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
76c0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
76d0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
76e0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
76f0: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
7700: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
7710: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
7720: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
7730: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
7740: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
7750: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
7760: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7770: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
7780: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
7790: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
77a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
77b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
77c0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
77d0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
77e0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
77f0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
7800: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
7810: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
7820: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
7830: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
7840: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
7850: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
7860: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
7870: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
7880: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
7890: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
78a0: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
78b0: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
78c0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
78d0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
78e0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
78f0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
7900: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
7910: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
7920: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7930: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
7940: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
7950: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
7960: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
7970: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
7980: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
7990: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
79a0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
79b0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
79c0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
79d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
79e0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
79f0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
7a00: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
7a10: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
7a20: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
7a30: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
7a40: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
7a50: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
7a60: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
7a70: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7a80: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
7a90: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
7aa0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
7ab0: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
7ac0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
7ad0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
7ae0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
7af0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
7b00: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
7b10: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
7b20: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
7b30: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
7b40: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
7b50: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
7b60: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
7b70: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
7b80: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
7b90: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7ba0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
7bb0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7bc0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
7bd0: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
7be0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7bf0: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
7c00: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
7c10: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
7c20: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
7c30: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
7c40: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
7c50: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
7c60: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
7c70: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
7c80: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
7c90: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
7ca0: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
7cb0: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
7cc0: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
7cd0: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
7ce0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7cf0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
7d00: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
7d10: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
7d20: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
7d30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
7d40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
7d50: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
7d60: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
7d70: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
7d80: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
7d90: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
7da0: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
7db0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
7dc0: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
7dd0: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
7de0: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
7df0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
7e00: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
7e10: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
7e20: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
7e30: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
7e40: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
7e50: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
7e60: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
7e70: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
7e80: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
7e90: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
7ea0: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
7eb0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
7ec0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7ed0: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
7ee0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
7ef0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7f00: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
7f10: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7f20: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
7f30: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
7f40: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
7f50: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
7f60: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
7f70: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
7f80: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
7f90: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
7fa0: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
7fb0: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
7fc0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
7fd0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
7fe0: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
7ff0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
8000: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
8010: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
8020: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
8030: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
8040: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
8050: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
8060: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
8070: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
8080: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
8090: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
80a0: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
80b0: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
80c0: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
80d0: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
80e0: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
80f0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
8100: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
8110: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
8120: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
8130: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8140: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
8150: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
8160: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
8170: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
8180: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
8190: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
81a0: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
81b0: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
81c0: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
81d0: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
81e0: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
81f0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
8200: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
8210: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
8220: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
8230: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
8240: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
8250: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
8260: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
8270: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
8280: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
8290: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
82a0: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
82b0: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
82c0: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
82d0: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
82e0: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
82f0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
8300: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
8310: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
8320: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
8330: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
8340: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66  own use..** A [f
8350: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8360: 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  des | list of op
8370: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
8380: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
8390: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
83a0: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
83b0: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
83c0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
83d0: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
83e0: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
83f0: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
8400: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
8410: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
8420: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
8430: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
8440: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
8450: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
8460: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
8470: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
8480: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
8490: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
84a0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
84b0: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
84c0: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
84d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
84e0: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
84f0: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
8500: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
8510: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
8520: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
8530: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
8540: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
8550: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
8560: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
8570: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
8580: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
8590: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
85a0: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
85b0: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
85c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
85d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
85e0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
85f0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
8600: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8610: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
8620: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8630: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
8640: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8650: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
8660: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8670: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
8680: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8690: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
86a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
86b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
86c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
86d0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
86e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
86f0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
8700: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
8710: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8720: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  NTIAL].** <li> [
8730: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
8740: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
8750: 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  EN].** <li> [SQL
8760: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
8770: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 0a 2a  AFE_OVERWRITE].*
8780: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8790: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 0a  OCAP_IMMUTABLE].
87a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
87b0: 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d  IOCAP_BATCH_ATOM
87c0: 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  IC].** </ul>.**.
87d0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
87e0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
87f0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
8800: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
8810: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
8820: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8830: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
8840: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
8850: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
8860: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
8870: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
8880: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
8890: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
88a0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
88b0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
88c0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
88d0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
88e0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
88f0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
8900: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
8910: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
8920: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
8930: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
8940: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
8950: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
8960: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
8970: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
8980: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
8990: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
89a0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
89b0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
89c0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
89d0: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
89e0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
89f0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
8a00: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
8a10: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
8a20: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
8a30: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
8a40: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
8a50: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
8a60: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
8a70: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
8a80: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
8a90: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
8aa0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
8ab0: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
8ac0: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
8ad0: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
8ae0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8af0: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
8b00: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
8b10: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
8b20: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
8b30: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8b40: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
8b50: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
8b60: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8b70: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
8b80: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
8b90: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
8ba0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
8bb0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
8bc0: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
8bd0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8be0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8bf0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
8c00: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
8c10: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8c20: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8c30: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8c40: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
8c50: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8c60: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
8c70: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
8c80: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8c90: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
8ca0: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
8cb0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8cc0: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
8cd0: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
8ce0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8cf0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
8d00: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
8d10: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8d20: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
8d30: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
8d40: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
8d50: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
8d60: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
8d70: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
8d80: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
8d90: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
8da0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
8db0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
8dc0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8dd0: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
8de0: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
8df0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8e00: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
8e10: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
8e20: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8e30: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
8e40: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
8e50: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
8e60: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
8e70: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8e80: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
8e90: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
8ea0: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
8eb0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8ec0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
8ed0: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
8ee0: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
8ef0: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
8f00: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8f10: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
8f20: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63  */.  int (*xFetc
8f30: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8f40: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8f50: 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c  iOfst, int iAmt,
8f60: 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69   void **pp);.  i
8f70: 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73  nt (*xUnfetch)(s
8f80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8f90: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8fa0: 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f  t, void *p);.  /
8fb0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8fc0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8fd0: 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20  rsion 3 */.  /* 
8fe0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8ff0: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
9000: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
9010: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
9020: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
9030: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
9040: 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  Opcodes.** KEYWO
9050: 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72  RDS: {file contr
9060: 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c  ol opcodes} {fil
9070: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
9080: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  }.**.** These in
9090: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
90a0: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
90b0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
90c0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
90d0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
90e0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
90f0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
9100: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9110: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
9120: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
9130: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9140: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a  L_LOCKSTATE]].**
9150: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9160: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
9170: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
9180: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
9190: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
91a0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
91b0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
91c0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
91d0: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
91e0: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
91f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
9200: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
9210: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
9220: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
9230: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
9240: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
9250: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
9260: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
9270: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
9280: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
9290: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
92a0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
92b0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
92c0: 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20  ing and is only 
92d0: 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74  available when t
92e0: 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  he SQLITE_TEST.*
92f0: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
9300: 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
9310: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9320: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
9330: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
9340: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
9350: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
9360: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
9370: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
9380: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
9390: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
93a0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
93b0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
93c0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
93d0: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
93e0: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
93f0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
9400: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
9410: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
9420: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
9430: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
9440: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
9450: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
9460: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
9470: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
9480: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
9490: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
94a0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
94b0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
94c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
94d0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
94e0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
94f0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
9500: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9510: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
9520: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
9530: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
9540: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
9550: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
9560: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
9570: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
9580: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
9590: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
95a0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
95b0: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
95c0: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
95d0: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
95e0: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
95f0: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
9600: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
9610: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
9620: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
9630: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
9640: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
9650: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
9660: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
9670: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
9680: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
9690: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
96a0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
96b0: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
96c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
96d0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
96e0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
96f0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9700: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9710: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9720: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9730: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9740: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9750: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
9760: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
9770: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
9780: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
9790: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
97a0: 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ER]..**.** <li>[
97b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
97c0: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a  URNAL_POINTER]].
97d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
97e0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
97f0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
9800: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
9810: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
9820: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9830: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
9840: 74 65 64 20 77 69 74 68 20 74 68 65 20 6a 6f 75  ted with the jou
9850: 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 68 65  rnal file (eithe
9860: 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61  r.** the [rollba
9870: 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74  ck journal] or t
9880: 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 64 20  he [write-ahead 
9890: 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 72 74  log]) for a part
98a0: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
98b0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
98c0: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
98d0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
98e0: 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  TER]..**.** <li>
98f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
9900: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a  YNC_OMITTED]].**
9910: 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73   No longer in us
9920: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
9930: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9940: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
9950: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70  E_FCNTL_SYNC] op
9960: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
9970: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
9980: 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65  SQLite and.** se
9990: 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d  nt to the VFS im
99a0: 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65  mediately before
99b0: 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f   the xSync metho
99c0: 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  d is invoked on 
99d0: 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69  a.** database fi
99e0: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f  le descriptor. O
99f0: 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20  r, if the xSync 
9a00: 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e  method is not in
9a10: 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73  voked .** becaus
9a20: 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63  e the user has c
9a30: 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65  onfigured SQLite
9a40: 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d   with .** [PRAGM
9a50: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20  A synchronous | 
9a60: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
9a70: 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e  us=OFF] it is in
9a80: 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a  voked in place .
9a90: 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20  ** of the xSync 
9aa0: 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20  method. In most 
9ab0: 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74  cases, the point
9ac0: 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  er argument pass
9ad0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20  ed with.** this 
9ae0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
9af0: 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69  NULL. However, i
9b00: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
9b10: 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e  ile is being syn
9b20: 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  ced.** as part o
9b30: 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61  f a multi-databa
9b40: 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61  se commit, the a
9b50: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
9b60: 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  o a nul-terminat
9b70: 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ed.** string con
9b80: 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e  taining the tran
9b90: 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d  sactions master-
9ba0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d  journal file nam
9bb0: 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a  e. VFSes that .*
9bc0: 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  * do not need th
9bd0: 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64  is signal should
9be0: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9bf0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
9c00: 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73  plications .** s
9c10: 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b  hould not call [
9c20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9c30: 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69  trol()] with thi
9c40: 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  s opcode as doin
9c50: 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73  g so may .** dis
9c60: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
9c70: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
9c80: 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74  lized VFSes that
9c90: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
9ca0: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
9cb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
9cc0: 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20  T_PHASETWO]].** 
9cd0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9ce0: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
9cf0: 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  O] opcode is gen
9d00: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
9d10: 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  y by SQLite.** a
9d20: 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56  nd sent to the V
9d30: 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73  FS after a trans
9d40: 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20  action has been 
9d50: 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69  committed immedi
9d60: 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66  ately.** but bef
9d70: 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ore the database
9d80: 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46   is unlocked. VF
9d90: 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20  Ses that do not 
9da0: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
9db0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  .** should silen
9dc0: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
9dd0: 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74  opcode. Applicat
9de0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ions should not 
9df0: 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
9e00: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9e10: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
9e20: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
9e30: 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a  y disrupt the .*
9e40: 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  * operation of t
9e50: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
9e60: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
9e70: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
9e80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9e90: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9ea0: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
9eb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
9ec0: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
9ed0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
9ee0: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
9ef0: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
9f00: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
9f10: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
9f20: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
9f30: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
9f40: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
9f50: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
9f60: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
9f70: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
9f80: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
9f90: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
9fa0: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
9fb0: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
9fc0: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
9fd0: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
9fe0: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
9ff0: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
a000: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
a010: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
a020: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
a030: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
a040: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
a050: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
a060: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
a070: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
a080: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
a090: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
a0a0: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
a0b0: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
a0c0: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
a0d0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
a0e0: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
a0f0: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
a100: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
a110: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
a120: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
a130: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
a140: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
a150: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
a160: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
a170: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
a180: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
a190: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
a1a0: 73 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  s the new retry 
a1b0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
a1c0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
a1d0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
a1e0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
a1f0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
a200: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
a210: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
a220: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
a230: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
a240: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
a250: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
a260: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
a270: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
a280: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
a290: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
a2a0: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
a2b0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
a2c0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
a2d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a2e0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
a2f0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
a300: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a310: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
a320: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
a330: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
a340: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
a350: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
a360: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
a370: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
a380: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
a390: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
a3a0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
a3b0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
a3c0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
a3d0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
a3e0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
a3f0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
a400: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
a410: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
a420: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
a430: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
a440: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
a450: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
a460: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
a470: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
a480: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
a490: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
a4a0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
a4b0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
a4c0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
a4d0: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
a4e0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
a4f0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
a500: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
a510: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
a520: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
a530: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
a540: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
a550: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
a560: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
a570: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
a580: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
a590: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a5a0: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
a5b0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
a5c0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
a5d0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
a5e0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
a5f0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
a600: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
a610: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
a620: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
a630: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a640: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a650: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a660: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a670: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a680: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a690: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a6a0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a6b0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a6c0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a6d0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a6e0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a6f0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a700: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a710: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a720: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a730: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a740: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a750: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a760: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a770: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a780: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a790: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a7a0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a7b0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a7c0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a7d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a7e0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a7f0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a800: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a810: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a820: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a830: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a840: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a850: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a860: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a870: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a880: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a890: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a8a0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a8b0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a8c0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a8d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a8e0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a8f0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a900: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a910: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a920: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a930: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a940: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a950: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a960: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a970: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a980: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a990: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a9a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a9b0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a9c0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a9d0: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a9e0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a9f0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
aa00: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
aa10: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
aa20: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
aa30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
aa40: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
aa50: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
aa60: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
aa70: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
aa80: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
aa90: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
aaa0: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
aab0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
aac0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
aad0: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
aae0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
aaf0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
ab00: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
ab10: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
ab20: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
ab30: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
ab40: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
ab50: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
ab60: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
ab70: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
ab80: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
ab90: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
aba0: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
abb0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
abc0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
abd0: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
abe0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
abf0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
ac00: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
ac10: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
ac20: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
ac30: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
ac40: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
ac50: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
ac60: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
ac70: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
ac80: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
ac90: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
aca0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
acb0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
acc0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
acd0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
ace0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
acf0: 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e  S_POINTER]].** ^
ad00: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ad10: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f  L_VFS_POINTER] o
ad20: 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f  pcode finds a po
ad30: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
ad40: 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73  -level.** [VFSes
ad50: 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75  ] currently in u
ad60: 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  se.  ^(The argum
ad70: 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69  ent X in.** sqli
ad80: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
ad90: 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c  (db,SQLITE_FCNTL
ada0: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20  _VFS_POINTER,X) 
adb0: 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79  must be.** of ty
adc0: 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73  pe "[sqlite3_vfs
add0: 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63  ] **".  This opc
ade0: 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58  odes will set *X
adf0: 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72  .** to a pointer
ae00: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65   to the top-leve
ae10: 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65  l VFS.)^.** ^Whe
ae20: 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74  n there are mult
ae30: 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69  iple VFS shims i
ae40: 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69  n the stack, thi
ae50: 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74  s opcode finds t
ae60: 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74  he.** upper-most
ae70: 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a   shim only..**.*
ae80: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ae90: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
aea0: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
aeb0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
aec0: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
aed0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
aee0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
aef0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
af00: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
af10: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
af20: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
af30: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
af40: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
af50: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
af60: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
af70: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
af80: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
af90: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
afa0: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
afb0: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
afc0: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
afd0: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
afe0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
aff0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
b000: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
b010: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
b020: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
b030: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
b040: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
b050: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
b060: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
b070: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
b080: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
b090: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
b0a0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
b0b0: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
b0c0: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
b0d0: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
b0e0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
b0f0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
b100: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
b110: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
b120: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
b130: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
b140: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
b150: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
b160: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
b170: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
b180: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
b190: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
b1a0: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
b1b0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
b1c0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
b1d0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
b1e0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
b1f0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
b200: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
b210: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
b220: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b230: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
b240: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
b250: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
b260: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
b270: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
b280: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
b290: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
b2a0: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
b2b0: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
b2c0: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
b2d0: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
b2e0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
b2f0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
b300: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
b310: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
b320: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
b330: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
b340: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
b350: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
b360: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
b370: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
b380: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
b390: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
b3a0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
b3b0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
b3c0: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
b3d0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
b3e0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
b3f0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
b400: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
b410: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
b420: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
b430: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
b440: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b450: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
b460: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
b470: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
b480: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
b490: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
b4a0: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
b4b0: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
b4c0: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
b4d0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
b4e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b4f0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
b500: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
b510: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b520: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
b530: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
b540: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
b550: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
b560: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
b570: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
b580: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
b590: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
b5a0: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
b5b0: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
b5c0: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
b5d0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
b5e0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
b5f0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
b600: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
b610: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
b620: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
b630: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
b640: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
b650: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
b660: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
b670: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
b680: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
b690: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
b6a0: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
b6b0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
b6c0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
b6d0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
b6e0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
b6f0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
b700: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
b710: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
b720: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
b730: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
b740: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
b750: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
b760: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
b770: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
b780: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
b790: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
b7a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b7b0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
b7c0: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
b7d0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
b7e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b7f0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
b800: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
b810: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
b820: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
b830: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
b840: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
b850: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
b860: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
b870: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b880: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
b890: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
b8a0: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
b8b0: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
b8c0: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
b8d0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
b8e0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b8f0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
b900: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b910: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
b920: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b930: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
b940: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
b950: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b960: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
b970: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
b980: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b990: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b9a0: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b9b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b9c0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b9d0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b9e0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b9f0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
ba00: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
ba10: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
ba20: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
ba30: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
ba40: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
ba50: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
ba60: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
ba70: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
ba80: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
ba90: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
baa0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
bab0: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
bac0: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
bad0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
bae0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
baf0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
bb00: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
bb10: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
bb20: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
bb30: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
bb40: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
bb50: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
bb60: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
bb70: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
bb80: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
bb90: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
bba0: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
bbb0: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
bbc0: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
bbd0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
bbe0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
bbf0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
bc00: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
bc10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
bc20: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
bc30: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
bc40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
bc50: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
bc60: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
bc70: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
bc80: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
bc90: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
bca0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
bcb0: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
bcc0: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
bcd0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
bce0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
bcf0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
bd00: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
bd10: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
bd20: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
bd30: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
bd40: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
bd50: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
bd60: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
bd70: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
bd80: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
bd90: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
bda0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bdb0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
bdc0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bdd0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
bde0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
bdf0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
be00: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
be10: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
be20: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
be30: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
be40: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
be50: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
be60: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
be70: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
be80: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
be90: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
bea0: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
beb0: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
bec0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bed0: 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c  _WIN32_GET_HANDL
bee0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
bef0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
bf00: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
bf10: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
bf20: 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75   obtain the.** u
bf30: 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76 65  nderlying native
bf40: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73 73   file handle ass
bf50: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 66  ociated with a f
bf60: 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68 69  ile handle.  Thi
bf70: 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f  s file.** contro
bf80: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
bf90: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20 70   argument as a p
bfa0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74 69  ointer to a nati
bfb0: 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61  ve file handle a
bfc0: 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68 65  nd.** writes the
bfd0: 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75 65   resulting value
bfe0: 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c   there..**.** <l
bff0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c000: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
c010: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
c020: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
c030: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
c040: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
c050: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
c060: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
c070: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
c080: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
c090: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
c0a0: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
c0b0: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
c0c0: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
c0d0: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
c0e0: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
c0f0: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
c100: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
c110: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
c120: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
c130: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
c140: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c150: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
c160: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c170: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
c180: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
c190: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
c1a0: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
c1b0: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
c1c0: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
c1d0: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
c1e0: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
c1f0: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
c200: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
c210: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
c220: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
c230: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
c240: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
c250: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
c260: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
c270: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
c280: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
c290: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
c2a0: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
c2b0: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
c2c0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c2d0: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
c2e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
c2f0: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
c300: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
c310: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
c320: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
c330: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
c340: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
c350: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
c360: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c370: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68  CNTL_RBU]].** Th
c380: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c390: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  RBU] opcode is i
c3a0: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
c3b0: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
c3c0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55  ed by.** the RBU
c3d0: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
c3e0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
c3f0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
c400: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
c410: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
c420: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
c430: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
c440: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IN_ATOMIC_WRITE]
c450: 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 51 4c  ].** If the [SQL
c460: 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f  ITE_FCNTL_BEGIN_
c470: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70  ATOMIC_WRITE] op
c480: 63 6f 64 65 20 72 65 74 75 72 6e 73 20 53 51 4c  code returns SQL
c490: 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a 2a 20  ITE_OK, then.** 
c4a0: 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  the file descrip
c4b0: 74 6f 72 20 69 73 20 70 6c 61 63 65 64 20 69 6e  tor is placed in
c4c0: 20 22 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f   "batch write mo
c4d0: 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a 20 6d 65  de", which.** me
c4e0: 61 6e 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65  ans all subseque
c4f0: 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61 74 69  nt write operati
c500: 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64 65 66 65  ons will be defe
c510: 72 72 65 64 20 61 6e 64 20 64 6f 6e 65 0a 2a 2a  rred and done.**
c520: 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61 74 20 74   atomically at t
c530: 68 65 20 6e 65 78 74 20 5b 53 51 4c 49 54 45 5f  he next [SQLITE_
c540: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c550: 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20 53 79 73  MIC_WRITE].  Sys
c560: 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20  tems.** that do 
c570: 6e 6f 74 20 73 75 70 70 6f 72 74 20 62 61 74 63  not support batc
c580: 68 20 61 74 6f 6d 69 63 20 77 72 69 74 65 73 20  h atomic writes 
c590: 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
c5a0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a 2a 20  TE_NOTFOUND..** 
c5b0: 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 73 75 63  ^Following a suc
c5c0: 63 65 73 73 66 75 6c 20 53 51 4c 49 54 45 5f 46  cessful SQLITE_F
c5d0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
c5e0: 43 5f 57 52 49 54 45 20 61 6e 64 20 70 72 69 6f  C_WRITE and prio
c5f0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6c 6f 73  r to.** the clos
c600: 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  ing [SQLITE_FCNT
c610: 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f  L_COMMIT_ATOMIC_
c620: 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b 53 51  WRITE] or.** [SQ
c630: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
c640: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
c650: 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6d  ], SQLite will m
c660: 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53 20 69 6e  ake.** no VFS in
c670: 74 65 72 66 61 63 65 20 63 61 6c 6c 73 20 6f 6e  terface calls on
c680: 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c 69 74   the same [sqlit
c690: 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65 20 64 65  e3_file] file de
c6a0: 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65 78 63 65  scriptor.** exce
c6b0: 70 74 20 66 6f 72 20 63 61 6c 6c 73 20 74 6f 20  pt for calls to 
c6c0: 74 68 65 20 78 57 72 69 74 65 20 6d 65 74 68 6f  the xWrite metho
c6d0: 64 20 61 6e 64 20 74 68 65 20 78 46 69 6c 65 43  d and the xFileC
c6e0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
c6f0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 46 43   with [SQLITE_FC
c700: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 2e 0a  NTL_SIZE_HINT]..
c710: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c720: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c730: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a  ATOMIC_WRITE]].*
c740: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c750: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
c760: 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  C_WRITE] opcode 
c770: 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65  causes all write
c780: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73  .** operations s
c790: 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75  ince the previou
c7a0: 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  s successful cal
c7b0: 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  l to .** [SQLITE
c7c0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
c7d0: 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65  MIC_WRITE] to be
c7e0: 20 70 65 72 66 6f 72 6d 65 64 20 61 74 6f 6d 69   performed atomi
c7f0: 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73 20 66  cally..** This f
c800: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
c810: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
c820: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
c830: 68 65 20 77 72 69 74 65 73 20 77 65 72 65 0a 2a  he writes were.*
c840: 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d 65 64 20  * all performed 
c850: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 6e 64  successfully and
c860: 20 68 61 76 65 20 62 65 65 6e 20 63 6f 6d 6d 69   have been commi
c870: 74 74 65 64 20 74 6f 20 70 65 72 73 69 73 74 65  tted to persiste
c880: 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a 2a 20 5e  nt storage..** ^
c890: 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
c8a0: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20  ether or not it 
c8b0: 69 73 20 73 75 63 63 65 73 73 66 75 6c 2c 20 74  is successful, t
c8c0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
c8d0: 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65 20 66 69   takes.** the fi
c8e0: 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75  le descriptor ou
c8f0: 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65  t of batch write
c900: 20 6d 6f 64 65 20 73 6f 20 74 68 61 74 20 61 6c   mode so that al
c910: 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  l subsequent.** 
c920: 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  write operations
c930: 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74   are independent
c940: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
c950: 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53  l never invoke S
c960: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
c970: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20  IT_ATOMIC_WRITE 
c980: 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 69  without.** a pri
c990: 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
c9a0: 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 43  ll to [SQLITE_FC
c9b0: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
c9c0: 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  _WRITE]..**.** <
c9d0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c9e0: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
c9f0: 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65  C_WRITE]].** The
ca00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52   [SQLITE_FCNTL_R
ca10: 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57  OLLBACK_ATOMIC_W
ca20: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 61 75  RITE] opcode cau
ca30: 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a 2a 2a  ses all write.**
ca40: 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 6e 63   operations sinc
ca50: 65 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  e the previous s
ca60: 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
ca70: 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  o .** [SQLITE_FC
ca80: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
ca90: 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20 72 6f  _WRITE] to be ro
caa0: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 5e 54  lled back..** ^T
cab0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
cac0: 20 74 61 6b 65 73 20 74 68 65 20 66 69 6c 65 20   takes the file 
cad0: 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74 20 6f  descriptor out o
cae0: 66 20 62 61 74 63 68 20 77 72 69 74 65 20 6d 6f  f batch write mo
caf0: 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74 20 61 6c  de.** so that al
cb00: 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77 72 69  l subsequent wri
cb10: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  te operations ar
cb20: 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e 0a 2a  e independent..*
cb30: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
cb40: 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 4c 49  ever invoke SQLI
cb50: 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43  TE_FCNTL_ROLLBAC
cb60: 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 77  K_ATOMIC_WRITE w
cb70: 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 69 6f  ithout.** a prio
cb80: 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
cb90: 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  l to [SQLITE_FCN
cba0: 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f  TL_BEGIN_ATOMIC_
cbb0: 57 52 49 54 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  WRITE]..** </ul>
cbc0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
cbd0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
cbe0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
cbf0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
cc00: 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b  E_FCNTL_GET_LOCK
cc10: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
cc20: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
cc30: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
cc40: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33  ROXYFILE       3
cc50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cc60: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
cc70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a                4.
cc80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cc90: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20  CNTL_SIZE_HINT  
cca0: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
ccb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ccc0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20  NTL_CHUNK_SIZE  
ccd0: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
cce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ccf0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20  TL_FILE_POINTER 
cd00: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
cd10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cd20: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20  L_SYNC_OMITTED  
cd30: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66            8.#def
cd40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cd50: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20  _WIN32_AV_RETRY 
cd60: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
cd70: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cd80: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20  PERSIST_WAL     
cd90: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
cda0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  e SQLITE_FCNTL_O
cdb0: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20  VERWRITE        
cdc0: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
cdd0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46   SQLITE_FCNTL_VF
cde0: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  SNAME           
cdf0: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20       12.#define 
ce00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
ce10: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
ce20: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
ce30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ce40: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
ce50: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51     14.#define SQ
ce60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
ce70: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20  ANDLER          
ce80: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    15.#define SQL
ce90: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
cea0: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  LENAME          
ceb0: 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   16.#define SQLI
cec0: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
ced0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
cee0: 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  18.#define SQLIT
cef0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20  E_FCNTL_TRACE   
cf00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
cf10: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
cf20: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
cf30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
cf40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cf50: 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20  FCNTL_SYNC      
cf60: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a               21.
cf70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cf80: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53  CNTL_COMMIT_PHAS
cf90: 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23  ETWO        22.#
cfa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cfb0: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
cfc0: 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64  NDLE       23.#d
cfd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cfe0: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20  TL_WAL_BLOCK    
cff0: 20 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65            24.#de
d000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d010: 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20  L_ZIPVFS        
d020: 20 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66           25.#def
d030: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d040: 5f 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20  _RBU            
d050: 20 20 20 20 20 20 20 20 32 36 0a 23 64 65 66 69          26.#defi
d060: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d070: 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  VFS_POINTER     
d080: 20 20 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e         27.#defin
d090: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a  e SQLITE_FCNTL_J
d0a0: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20  OURNAL_POINTER  
d0b0: 20 20 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65        28.#define
d0c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
d0d0: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20  N32_GET_HANDLE  
d0e0: 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20       29.#define 
d0f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42  SQLITE_FCNTL_PDB
d100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d110: 20 20 20 20 33 30 0a 23 64 65 66 69 6e 65 20 53      30.#define S
d120: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
d130: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20  N_ATOMIC_WRITE  
d140: 20 20 20 33 31 0a 23 64 65 66 69 6e 65 20 53 51     31.#define SQ
d150: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
d160: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 20  T_ATOMIC_WRITE  
d170: 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    32.#define SQL
d180: 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41  ITE_FCNTL_ROLLBA
d190: 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20  CK_ATOMIC_WRITE 
d1a0: 20 33 33 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74   33../* deprecat
d1b0: 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66  ed names */.#def
d1c0: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
d1d0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
d1e0: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47    SQLITE_FCNTL_G
d1f0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
d200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d210: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
d220: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
d230: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
d240: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
d250: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
d260: 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49              SQLI
d270: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
d280: 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  RNO.../*.** CAPI
d290: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
d2a0: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
d2b0: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
d2c0: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
d2d0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
d2e0: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
d2f0: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
d300: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
d310: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
d320: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
d330: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
d340: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
d350: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
d360: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
d370: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
d380: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
d390: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
d3a0: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
d3b0: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
d3c0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
d3d0: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
d3e0: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
d3f0: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
d400: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
d410: 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
d420: 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54  able Extension T
d430: 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  hunk.**.** A poi
d440: 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71  nter to the opaq
d450: 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ue sqlite3_api_r
d460: 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74 75 72  outines structur
d470: 65 20 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a  e is passed as.*
d480: 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  * the third para
d490: 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70  meter to entry p
d4a0: 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62  oints of [loadab
d4b0: 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20  le extensions]. 
d4c0: 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75   This.** structu
d4d0: 72 65 20 6d 75 73 74 20 62 65 20 74 79 70 65 64  re must be typed
d4e0: 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  efed in order to
d4f0: 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d   work around com
d500: 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a  piler warnings.*
d510: 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f  * on some platfo
d520: 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  rms..*/.typedef 
d530: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61  struct sqlite3_a
d540: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69  pi_routines sqli
d550: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
d560: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
d570: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
d580: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
d590: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
d5a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
d5b0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
d5c0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
d5d0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
d5e0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
d5f0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
d600: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
d610: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
d620: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
d630: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
d640: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
d650: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
d660: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
d670: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
d680: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
d690: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 56 46 53 20  ..**.** The VFS 
d6a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 6f 6d  interface is som
d6b0: 65 74 69 6d 65 73 20 65 78 74 65 6e 64 65 64 20  etimes extended 
d6c0: 62 79 20 61 64 64 69 6e 67 20 6e 65 77 20 6d 65  by adding new me
d6d0: 74 68 6f 64 73 20 6f 6e 74 6f 0a 2a 2a 20 74 68  thods onto.** th
d6e0: 65 20 65 6e 64 2e 20 20 45 61 63 68 20 74 69 6d  e end.  Each tim
d6f0: 65 20 73 75 63 68 20 61 6e 20 65 78 74 65 6e 73  e such an extens
d700: 69 6f 6e 20 6f 63 63 75 72 73 2c 20 74 68 65 20  ion occurs, the 
d710: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 0a 2a  iVersion field.*
d720: 2a 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64  * is incremented
d730: 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 20  .  The iVersion 
d740: 76 61 6c 75 65 20 73 74 61 72 74 65 64 20 6f 75  value started ou
d750: 74 20 61 73 20 31 20 69 6e 0a 2a 2a 20 53 51 4c  t as 1 in.** SQL
d760: 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 35  ite [version 3.5
d770: 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33  .0] on [dateof:3
d780: 2e 35 2e 30 5d 2c 20 74 68 65 6e 20 69 6e 63 72  .5.0], then incr
d790: 65 61 73 65 64 20 74 6f 20 32 0a 2a 2a 20 77 69  eased to 2.** wi
d7a0: 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69  th SQLite [versi
d7b0: 6f 6e 20 33 2e 37 2e 30 5d 20 6f 6e 20 5b 64 61  on 3.7.0] on [da
d7c0: 74 65 6f 66 3a 33 2e 37 2e 30 5d 2c 20 61 6e 64  teof:3.7.0], and
d7d0: 20 74 68 65 6e 20 69 6e 63 72 65 61 73 65 64 0a   then increased.
d7e0: 2a 2a 20 74 6f 20 33 20 77 69 74 68 20 53 51 4c  ** to 3 with SQL
d7f0: 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 37  ite [version 3.7
d800: 2e 36 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 3a 33  .6] on [dateof:3
d810: 2e 37 2e 36 5d 2e 20 20 41 64 64 69 74 69 6f 6e  .7.6].  Addition
d820: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 6d 61 79  al fields.** may
d830: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
d840: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
d850: 6f 62 6a 65 63 74 20 61 6e 64 20 74 68 65 20 69  object and the i
d860: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 0a 2a 2a  Version value.**
d870: 20 6d 61 79 20 69 6e 63 72 65 61 73 65 20 61 67   may increase ag
d880: 61 69 6e 20 69 6e 20 66 75 74 75 72 65 20 76 65  ain in future ve
d890: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
d8a0: 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  ..** Note that t
d8b0: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
d8c0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
d8d0: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
d8e0: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 69 74  s in the transit
d8f0: 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 53 51 4c 69  ion from.** SQLi
d900: 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 35 2e  te [version 3.5.
d910: 39 5d 20 74 6f 20 5b 76 65 72 73 69 6f 6e 20 33  9] to [version 3
d920: 2e 36 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66  .6.0] on [dateof
d930: 3a 33 2e 36 2e 30 5d 0a 2a 2a 20 61 6e 64 20 79  :3.6.0].** and y
d940: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
d950: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 20 6d 6f  field was not mo
d960: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
d970: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
d980: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
d990: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
d9a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
d9b0: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
d9c0: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
d9d0: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
d9e0: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
d9f0: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
da00: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
da10: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
da20: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
da30: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
da40: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
da50: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
da60: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
da70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
da80: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
da90: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
daa0: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
dab0: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
dac0: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
dad0: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
dae0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
daf0: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
db00: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
db10: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
db20: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
db30: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
db40: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
db50: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
db60: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
db70: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
db80: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
db90: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
dba0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
dbb0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
dbc0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
dbd0: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
dbe0: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
dbf0: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
dc00: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
dc10: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
dc20: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
dc30: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
dc40: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
dc50: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
dc60: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
dc70: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
dc80: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
dc90: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
dca0: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
dcb0: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
dcc0: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
dcd0: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
dce0: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
dcf0: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
dd00: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
dd10: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73  dules..**.** [[s
dd20: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
dd30: 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  ]].** ^SQLite gu
dd40: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
dd50: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
dd60: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
dd70: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
dd80: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
dd90: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
dda0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
ddb0: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
ddc0: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
ddd0: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
dde0: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
ddf0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
de00: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
de10: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
de20: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
de30: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
de40: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
de50: 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72  ** 11 alphanumer
de60: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
de70: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
de80: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
de90: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
dea0: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
deb0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
dec0: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
ded0: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
dee0: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
def0: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
df00: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
df10: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
df20: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
df30: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
df40: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
df50: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
df60: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
df70: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
df80: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
df90: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
dfa0: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
dfb0: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
dfc0: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
dfd0: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
dfe0: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
dff0: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
e000: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
e010: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
e020: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
e030: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
e040: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
e050: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
e060: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
e070: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
e080: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
e090: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
e0a0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
e0b0: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
e0c0: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
e0d0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
e0e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
e0f0: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
e100: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
e110: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
e120: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
e130: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
e140: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
e150: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
e160: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
e170: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
e180: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
e190: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
e1a0: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
e1b0: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
e1c0: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
e1d0: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
e1e0: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
e1f0: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
e200: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
e210: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
e220: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
e230: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
e240: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
e250: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
e260: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
e270: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
e280: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
e290: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
e2a0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
e2b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
e2c0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
e2d0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
e2e0: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
e2f0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
e300: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
e310: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e320: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
e330: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e340: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
e350: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e360: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
e370: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
e380: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
e390: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
e3a0: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
e3b0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e3c0: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
e3d0: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
e3e0: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
e3f0: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
e400: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
e410: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
e420: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
e430: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
e440: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
e450: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
e460: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
e470: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
e480: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
e490: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
e4a0: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
e4b0: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
e4c0: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
e4d0: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
e4e0: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
e4f0: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
e500: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
e510: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
e520: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
e530: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
e540: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
e550: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
e560: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
e570: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
e580: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
e590: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
e5a0: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
e5b0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
e5c0: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
e5d0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
e5e0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
e5f0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
e600: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
e610: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
e620: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
e630: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
e640: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
e650: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
e660: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
e670: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
e680: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
e690: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
e6a0: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
e6b0: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
e6c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
e6d0: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
e6e0: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
e6f0: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
e700: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
e710: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
e720: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
e730: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
e740: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
e750: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
e760: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
e770: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
e780: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
e790: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
e7a0: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
e7b0: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
e7c0: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
e7d0: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
e7e0: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
e7f0: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
e800: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
e810: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
e820: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
e830: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
e840: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
e850: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
e860: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
e870: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
e880: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
e890: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
e8a0: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
e8b0: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
e8c0: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
e8d0: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
e8e0: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
e8f0: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
e900: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
e910: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
e920: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
e930: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
e940: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
e950: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
e960: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
e970: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
e980: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
e990: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
e9a0: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
e9b0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
e9c0: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
e9d0: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
e9e0: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
e9f0: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
ea00: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
ea10: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
ea20: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
ea30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
ea40: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
ea50: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
ea60: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
ea70: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
ea80: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
ea90: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
eaa0: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
eab0: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
eac0: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
ead0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
eae0: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
eaf0: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
eb00: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
eb10: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
eb20: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
eb30: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
eb40: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b  en call..**.** [
eb50: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63  [sqlite3_vfs.xAc
eb60: 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66  cess]].** ^The f
eb70: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
eb80: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
eb90: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
eba0: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
ebb0: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
ebc0: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
ebd0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
ebe0: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
ebf0: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
ec00: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
ec10: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
ec20: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
ec30: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
ec40: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
ec50: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
ec60: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
ec70: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
ec80: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
ec90: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  * ^SQLite will a
eca0: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
ecb0: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
ecc0: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
ecd0: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
ece0: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
ecf0: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
ed00: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
ed10: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
ed20: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
ed30: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
ed40: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
ed50: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
ed60: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
ed70: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
ed80: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
ed90: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
eda0: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
edb0: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
edc0: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
edd0: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
ede0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
edf0: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
ee00: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
ee10: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
ee20: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
ee30: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
ee40: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
ee50: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
ee60: 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  , xCurrentTime()
ee70: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
ee80: 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74  meInt64().** int
ee90: 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20  erfaces are not 
eea0: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
eeb0: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
eec0: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
eed0: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
eee0: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
eef0: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
ef00: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
ef10: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
ef20: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
ef30: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
ef40: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
ef50: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
ef60: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
ef70: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
ef80: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
ef90: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
efa0: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
efb0: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
efc0: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
efd0: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
efe0: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
eff0: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
f000: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
f010: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
f020: 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54    ^The xCurrentT
f030: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
f040: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
f050: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
f060: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
f070: 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20   and time as.** 
f080: 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
f090: 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20   value..** ^The 
f0a0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
f0b0: 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  4() method retur
f0c0: 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65  ns, as an intege
f0d0: 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a  r, the Julian.**
f0e0: 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74   Day Number mult
f0f0: 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30  iplied by 864000
f100: 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f  00 (the number o
f110: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69  f milliseconds i
f120: 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20  n .** a 24-hour 
f130: 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69  day).  .** ^SQLi
f140: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
f150: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
f160: 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65  4() method to ge
f170: 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  t the current.**
f180: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69   date and time i
f190: 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73  f that method is
f1a0: 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69   available (if i
f1b0: 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20  Version is 2 or 
f1c0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20  .** greater and 
f1d0: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
f1e0: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
f1f0: 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20  ) and will fall 
f200: 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72  back.** to xCurr
f210: 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75  entTime() if xCu
f220: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
f230: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
f240: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74  .**.** ^The xSet
f250: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47  SystemCall(), xG
f260: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
f270: 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43  and xNestSystemC
f280: 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73  all() interfaces
f290: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64  .** are not used
f2a0: 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63   by the SQLite c
f2b0: 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69  ore.  These opti
f2c0: 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  onal interfaces 
f2d0: 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
f2e0: 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f  by some VFSes to
f2f0: 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74   facilitate test
f300: 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63  ing of the VFS c
f310: 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69  ode. By overridi
f320: 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61  ng .** system ca
f330: 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f  lls with functio
f340: 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e  ns under its con
f350: 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f  trol, a test pro
f360: 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75  gram can.** simu
f370: 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20  late faults and 
f380: 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73  error conditions
f390: 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65   that would othe
f3a0: 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75  rwise be difficu
f3b0: 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69  lt.** or impossi
f3c0: 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20  ble to induce.  
f3d0: 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65  The set of syste
f3e0: 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e  m calls that can
f3f0: 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a   be overridden.*
f400: 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  * varies from on
f410: 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72  e VFS to another
f420: 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76  , and from one v
f430: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61  ersion of the sa
f440: 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a  me VFS to the.**
f450: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
f460: 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68  ions that use th
f470: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
f480: 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20  ust be prepared 
f490: 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c  for any.** or al
f4a0: 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72  l of these inter
f4b0: 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c  faces to be NULL
f4c0: 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65   or for their be
f4d0: 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65  havior to change
f4e0: 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c  .** from one rel
f4f0: 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74  ease to the next
f500: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
f510: 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74  must not attempt
f520: 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e   to access.** an
f530: 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f  y of these metho
f540: 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69  ds if the iVersi
f550: 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73  on of the VFS is
f560: 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f   less than 3..*/
f570: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
f580: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
f590: 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66  te3_vfs;.typedef
f5a0: 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
f5b0: 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69  syscall_ptr)(voi
f5c0: 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  d);.struct sqlit
f5d0: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
f5e0: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
f5f0: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
f600: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
f610: 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f  (currently 3) */
f620: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
f630: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
f640: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
f650: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
f660: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
f670: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
f680: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
f690: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
f6a0: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
f6b0: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
f6c0: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
f6d0: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
f6e0: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
f6f0: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
f700: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
f710: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
f720: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
f730: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
f740: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
f750: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
f760: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
f770: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f780: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
f790: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
f7a0: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
f7b0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
f7c0: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
f7d0: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
f7e0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
f7f0: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
f800: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
f810: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
f820: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
f830: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
f840: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
f850: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
f860: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
f870: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
f880: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
f890: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
f8a0: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
f8b0: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
f8c0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
f8d0: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
f8e0: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
f8f0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
f900: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
f910: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
f920: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
f930: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
f940: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
f950: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
f960: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
f970: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
f980: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
f990: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
f9a0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
f9b0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
f9c0: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
f9d0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
f9e0: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
f9f0: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
fa00: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
fa10: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
fa20: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
fa30: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
fa40: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
fa50: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
fa60: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
fa70: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
fa80: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
fa90: 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69  object.  ** defi
faa0: 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74  nition.  Those t
fab0: 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61  hat follow are a
fac0: 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20  dded in version 
fad0: 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a  2 or later.  */.
fae0: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
faf0: 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74  TimeInt64)(sqlit
fb00: 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33  e3_vfs*, sqlite3
fb10: 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20  _int64*);.  /*. 
fb20: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
fb30: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
fb40: 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66  sions 1 and 2 of
fb50: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
fb60: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f  object..  ** Tho
fb70: 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72  se below are for
fb80: 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67   version 3 and g
fb90: 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69  reater..  */.  i
fba0: 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43  nt (*xSetSystemC
fbb0: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
fbc0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
fbd0: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79  Name, sqlite3_sy
fbe0: 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71  scall_ptr);.  sq
fbf0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
fc00: 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61  r (*xGetSystemCa
fc10: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
fc20: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
fc30: 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68  ame);.  const ch
fc40: 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65  ar *(*xNextSyste
fc50: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
fc60: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
fc70: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20  *zName);.  /*.  
fc80: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
fc90: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
fca0: 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33  ions 1 through 3
fcb0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
fcc0: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
fcd0: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
fce0: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 75  e appended in fu
fcf0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  ture versions.  
fd00: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
fd10: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
fd20: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
fd30: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20  this happens. . 
fd40: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
fd50: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
fd60: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
fd70: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
fd80: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
fd90: 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
fda0: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
fdb0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
fdc0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
fdd0: 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
fde0: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
fdf0: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
fe00: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
fe10: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
fe20: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
fe30: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a   looking for..**
fe40: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
fe50: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
fe60: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
fe70: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
fe80: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
fe90: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68   exists..** With
fea0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
feb0: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
fec0: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
fed0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
fee0: 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f  he named directo
fef0: 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  ry is both reada
ff00: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
ff10: 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f  .** (in other wo
ff20: 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61  rds, if files ca
ff30: 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f  n be added, remo
ff40: 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64  ved, and renamed
ff50: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64   within.** the d
ff60: 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68  irectory)..** Th
ff70: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ff80: 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61  READWRITE consta
ff90: 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  nt is currently 
ffa0: 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65  used only by the
ffb0: 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  .** [temp_store_
ffc0: 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
ffd0: 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63  ], though this c
ffe0: 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61  ould change in a
fff0: 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
10000 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
10010 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
10020 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
10030 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
10040 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
10050 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
10060 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
10070 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e  _ACCESS_READ con
10080 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72  stant is.** curr
10090 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68  ently unused, th
100a0 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65  ough it might be
100b0 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72   used in a futur
100c0 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
100d0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
100e0 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
100f0 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
10100 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
10110 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20  SS_READWRITE 1  
10120 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47   /* Used by PRAG
10130 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  MA temp_store_di
10140 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69  rectory */.#defi
10150 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
10160 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f  _READ      2   /
10170 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  * Unused */../*.
10180 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
10190 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c  gs for the xShmL
101a0 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ock VFS method.*
101b0 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
101c0 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  er constants def
101d0 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20  ine the various 
101e0 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f  locking operatio
101f0 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79  ns.** allowed by
10200 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   the xShmLock me
10210 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  thod of [sqlite3
10220 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54  _io_methods].  T
10230 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
10240 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67  are the only leg
10250 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  al combinations 
10260 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a  of flags to the.
10270 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  ** xShmLock meth
10280 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
10290 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
102a0 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
102b0 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
102c0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
102d0 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
102e0 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
102f0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
10300 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
10310 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
10320 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
10330 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
10340 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
10350 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  </ul>.**.** When
10360 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20   unlocking, the 
10370 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45  same SHARED or E
10380 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75  XCLUSIVE flag mu
10390 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61  st be supplied a
103a0 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f  s.** was given o
103b0 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
103c0 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a  ing lock.  .**.*
103d0 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
103e0 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69  ethod can transi
103f0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c  tion between unl
10400 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44  ocked and SHARED
10410 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75   or.** between u
10420 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c  nlocked and EXCL
10430 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f  USIVE.  It canno
10440 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  t transition bet
10450 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61  ween SHARED.** a
10460 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f  nd EXCLUSIVE..*/
10470 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10480 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  SHM_UNLOCK      
10490 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
104a0 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20  E_SHM_LOCK      
104b0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
104c0 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20  ITE_SHM_SHARED  
104d0 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
104e0 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
104f0 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20  IVE    8../*.** 
10500 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75  CAPI3REF: Maximu
10510 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78  m xShmLock index
10520 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
10530 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73  ock method on [s
10540 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
10550 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65  s] may use value
10560 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61  s.** between 0 a
10570 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f  nd this upper bo
10580 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73  und as its "offs
10590 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  et" argument..**
105a0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
105b0 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65   will never atte
105c0 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f  mpt to acquire o
105d0 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c  r release a.** l
105e0 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74  ock outside of t
105f0 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65  his range.*/.#de
10600 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
10610 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a  NLOCK        8..
10620 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10630 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
10640 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
10650 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
10660 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
10670 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
10680 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
10690 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
106a0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
106b0 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
106c0 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
106d0 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
106e0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
106f0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10700 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
10710 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
10720 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
10730 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
10740 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
10750 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
10760 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
10770 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
10780 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
10790 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
107a0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
107b0 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
107c0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
107d0 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
107e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
107f0 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
10800 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
10810 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
10820 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
10830 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
10840 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
10850 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
10860 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
10870 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
10880 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
10890 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
108a0 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
108b0 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
108c0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
108d0 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
108e0 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
108f0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10900 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
10910 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
10920 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
10930 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
10940 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
10950 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
10960 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
10970 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
10980 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
10990 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
109a0 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
109b0 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
109c0 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
109d0 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
109e0 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
109f0 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
10a00 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
10a10 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
10a20 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
10a30 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
10a40 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
10a50 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
10a60 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
10a70 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10a80 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
10a90 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
10aa0 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
10ab0 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
10ac0 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
10ad0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
10ae0 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
10af0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
10b00 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
10b10 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
10b20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10b30 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
10b40 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
10b50 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
10b60 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
10b70 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
10b80 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
10b90 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
10ba0 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
10bb0 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
10bc0 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
10bd0 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
10be0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
10bf0 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
10c00 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
10c10 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
10c20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
10c30 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
10c40 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
10c50 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
10c60 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
10c70 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
10c80 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
10c90 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
10ca0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
10cb0 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
10cc0 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
10cd0 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
10ce0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
10cf0 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
10d00 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
10d10 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
10d20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
10d30 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
10d40 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
10d50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
10d60 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10d70 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
10d80 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
10d90 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
10da0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
10db0 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
10dc0 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
10dd0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
10de0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
10df0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
10e00 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
10e10 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
10e20 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
10e30 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10e40 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
10e50 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
10e60 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
10e70 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
10e80 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
10e90 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
10ea0 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
10eb0 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
10ec0 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
10ed0 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
10ee0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
10ef0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
10f00 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
10f10 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
10f20 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
10f30 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
10f40 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10f50 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
10f60 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
10f70 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
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 0a 2a  ize() directly.*
10fa0 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
10fb0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
10fc0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
10fd0 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
10fe0 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
10ff0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
11000 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
11010 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
11020 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11030 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
11040 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
11050 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
11060 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
11070 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
11080 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
11090 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
110a0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
110b0 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
110c0 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
110d0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
110e0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
110f0 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
11100 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
11110 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
11120 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
11130 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
11140 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11150 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
11160 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
11170 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
11180 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
11190 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
111a0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
111b0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
111c0 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
111d0 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
111e0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
111f0 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
11200 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
11210 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
11220 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
11230 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
11240 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
11250 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
11260 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
11270 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
11280 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
11290 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
112a0 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
112b0 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
112c0 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
112d0 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
112e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
112f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
11300 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
11310 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
11320 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
11330 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
11340 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
11350 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
11360 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
11370 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
11380 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11390 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
113a0 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
113b0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
113c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
113d0 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
113e0 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
113f0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
11400 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
11410 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
11420 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
11430 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
11440 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
11450 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
11460 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
11470 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
11480 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
11490 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
114a0 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
114b0 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
114c0 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
114d0 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
114e0 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
114f0 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
11500 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
11510 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
11520 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
11530 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
11540 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
11550 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
11560 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
11570 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
11580 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
11590 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
115a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
115b0 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
115c0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
115d0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
115e0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
115f0 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
11600 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
11610 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
11620 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
11630 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
11640 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
11650 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
11660 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
11670 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
11680 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
11690 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
116a0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
116b0 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
116c0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
116d0 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
116e0 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
116f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11700 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
11710 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
11720 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
11730 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
11740 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
11750 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
11760 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
11770 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
11780 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
11790 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
117a0 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
117b0 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
117c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
117d0 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
117e0 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
117f0 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
11800 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
11810 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
11820 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
11830 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
11840 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69  *.** <b>The sqli
11850 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
11860 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
11870 72 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 70  readsafe. The ap
11880 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
11890 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t ensure that no
118a0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
118b0 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
118c0 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
118d0 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
118e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
118f0 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a  is running.</b>.
11900 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11910 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
11920 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  face.** may only
11930 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
11940 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
11950 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
11960 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
11970 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
11980 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
11990 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
119a0 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
119b0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
119c0 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
119d0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
119e0 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
119f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
11a00 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
11a10 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
11a20 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
11a30 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
11a40 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
11a50 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
11a60 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
11a70 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
11a80 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
11a90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
11aa0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11ab0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
11ac0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
11ad0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11ae0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
11af0 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
11b00 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
11b10 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
11b20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
11b30 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
11b40 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
11b50 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
11b60 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
11b70 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
11b80 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
11b90 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
11ba0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
11bb0 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
11bc0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
11bd0 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
11be0 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
11bf0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
11c00 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
11c10 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
11c20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
11c30 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
11c40 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
11c50 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
11c60 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
11c70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
11c80 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
11c90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
11ca0 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
11cb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11cc0 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
11cd0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
11ce0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
11cf0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
11d00 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f   used to make co
11d10 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
11d20 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74  hanges to a [dat
11d30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11d40 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  ].  The interfac
11d50 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a  e is similar to.
11d60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
11d70 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  ig()] except tha
11d80 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70  t the changes ap
11d90 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a  ply to a single.
11da0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11db0 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66  nection] (specif
11dc0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
11dd0 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a   argument)..**.*
11de0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
11df0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
11e00 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e  _db_config(D,V,.
11e10 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b  ..)  is the.** [
11e20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
11e30 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66  LOOKASIDE | conf
11e40 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20  iguration verb] 
11e50 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
11e60 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63  e .** that indic
11e70 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74  ates what aspect
11e80 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
11e90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
11ea0 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
11eb0 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74  d..** Subsequent
11ec0 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20   arguments vary 
11ed0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
11ee0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
11ef0 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  erb..**.** ^Call
11f00 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  s to sqlite3_db_
11f10 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20  config() return 
11f20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64  SQLITE_OK if and
11f30 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20   only if.** the 
11f40 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72  call is consider
11f50 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a  ed successful..*
11f60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  /.int sqlite3_db
11f70 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
11f80 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
11f90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11fa0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
11fb0 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
11fc0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
11fd0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
11fe0 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
11ff0 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
12000 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
12010 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
12020 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
12030 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
12040 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
12050 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
12060 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
12070 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
12080 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
12090 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
120a0 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
120b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
120c0 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
120d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
120e0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
120f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12100 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
12110 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
12120 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
12130 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
12140 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
12150 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
12160 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
12170 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
12180 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
12190 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
121a0 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
121b0 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
121c0 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
121d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
121e0 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
121f0 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
12200 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
12210 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
12220 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
12230 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
12240 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
12250 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
12260 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
12270 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
12280 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
12290 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
122a0 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
122b0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
122c0 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
122d0 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
122e0 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
122f0 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
12300 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
12310 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
12320 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
12330 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
12340 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
12350 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
12360 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
12370 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
12380 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
12390 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
123a0 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
123b0 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
123c0 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
123d0 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
123e0 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
123f0 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
12400 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
12410 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
12420 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
12430 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
12440 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
12450 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
12460 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
12470 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
12480 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
12490 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
124a0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
124b0 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
124c0 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
124d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
124e0 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
124f0 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
12500 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
12510 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
12520 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
12530 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
12540 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
12550 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
12560 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
12570 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
12580 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
12590 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
125a0 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
125b0 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
125c0 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
125d0 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
125e0 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
125f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
12600 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
12610 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
12620 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
12630 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
12640 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12650 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
12660 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
12670 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
12680 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
12690 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
126a0 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
126b0 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
126c0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
126d0 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
126e0 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
126f0 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
12700 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
12710 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
12720 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12730 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
12740 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
12750 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
12760 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
12770 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
12780 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
12790 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
127a0 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
127b0 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
127c0 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
127d0 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
127e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
127f0 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
12800 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
12810 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20  allocator.  For 
12820 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
12830 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
12840 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
12850 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
12860 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
12870 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
12880 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
12890 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
128a0 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
128b0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
128c0 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
128d0 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
128e0 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
128f0 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
12900 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
12910 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
12920 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
12930 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
12940 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
12950 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
12960 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
12970 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
12980 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
12990 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
129a0 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
129b0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
129c0 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
129d0 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
129e0 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
129f0 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
12a00 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
12a10 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
12a20 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
12a30 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
12a40 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
12a50 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
12a60 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
12a70 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
12a80 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
12a90 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
12aa0 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
12ab0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
12ac0 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
12ad0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
12ae0 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
12af0 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
12b00 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
12b10 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
12b20 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
12b30 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
12b40 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
12b50 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
12b60 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
12b70 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
12b80 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
12b90 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
12ba0 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
12bb0 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
12bc0 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
12bd0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
12be0 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
12bf0 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
12c00 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
12c10 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
12c20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
12c30 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
12c40 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
12c50 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
12c60 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
12c70 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
12c80 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
12c90 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
12ca0 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
12cb0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
12cc0 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
12cd0 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
12ce0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
12cf0 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
12d00 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12d10 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
12d20 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
12d30 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
12d40 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
12d50 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
12d60 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
12d70 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
12d80 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
12d90 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
12da0 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
12db0 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
12dc0 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
12dd0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
12de0 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
12df0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
12e00 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
12e10 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12e20 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
12e30 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
12e40 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
12e50 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
12e60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
12e70 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
12e80 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
12e90 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
12ea0 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
12eb0 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
12ec0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12ed0 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
12ee0 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
12ef0 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
12f00 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
12f10 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
12f20 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
12f30 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
12f40 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
12f50 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
12f60 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
12f70 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
12f80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
12f90 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
12fa0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
12fb0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12fc0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
12fd0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
12fe0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
12ff0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
13000 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
13010 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
13020 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
13030 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
13040 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
13050 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
13060 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
13070 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
13080 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
13090 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
130a0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
130b0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
130c0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
130d0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
130e0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
130f0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
13100 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13110 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
13120 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
13130 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
13140 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
13150 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
13160 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
13170 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
13180 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
13190 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
131a0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
131b0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
131c0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
131d0 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
131e0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
131f0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
13200 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
13210 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
13220 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
13230 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
13240 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
13250 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
13260 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
13270 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
13280 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
13290 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
132a0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
132b0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
132c0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
132d0 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
132e0 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
132f0 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
13300 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
13310 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
13320 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
13330 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
13340 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
13350 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
13360 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
13370 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
13380 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
13390 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
133a0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
133b0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
133c0 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
133d0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
133e0 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
133f0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
13400 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
13410 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
13420 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
13430 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
13440 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
13450 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
13460 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
13470 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
13480 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13490 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
134a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
134b0 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
134c0 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
134d0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
134e0 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
134f0 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
13500 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
13510 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
13520 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
13530 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
13540 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
13550 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
13560 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
13570 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
13580 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
13590 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
135a0 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
135b0 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
135c0 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
135d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
135e0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
135f0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13600 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13610 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13620 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13630 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
13640 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13650 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
13660 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
13670 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
13680 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
13690 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
136a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
136b0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
136c0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
136d0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
136e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
136f0 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
13700 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
13710 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13720 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
13730 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
13740 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
13750 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
13760 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
13770 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
13780 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
13790 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
137a0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
137b0 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
137c0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
137d0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
137e0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
137f0 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
13800 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
13810 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
13820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13830 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
13840 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
13850 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
13860 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
13870 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
13880 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13890 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
138a0 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
138b0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
138c0 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
138d0 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
138e0 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
138f0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
13900 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13910 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
13920 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
13930 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
13940 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
13950 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
13960 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
13970 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
13980 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
13990 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
139a0 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
139b0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
139c0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
139d0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
139e0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
139f0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
13a00 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
13a10 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
13a20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
13a30 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
13a40 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
13a50 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
13a60 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
13a70 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
13a80 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
13a90 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
13aa0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
13ab0 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
13ac0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
13ad0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13ae0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
13af0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13b00 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
13b10 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
13b20 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f  _CONFIG_MALLOC o
13b30 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
13b40 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
13b50 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
13b60 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
13b70 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
13b80 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
13b90 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
13ba0 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
13bb0 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
13bc0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
13bd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13be0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
13bf0 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
13c00 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
13c10 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
13c20 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
13c30 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
13c40 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
13c50 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
13c60 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
13c70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
13c80 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
13c90 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
13ca0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
13cb0 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
13cc0 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
13cd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13ce0 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
13cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13d00 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
13d10 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
13d20 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
13d30 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13d40 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13d50 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
13d60 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
13d70 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
13d80 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
13d90 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
13da0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
13db0 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
13dc0 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
13dd0 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
13de0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
13df0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
13e00 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
13e10 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
13e20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
13e30 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
13e40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
13e50 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
13e60 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
13e70 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
13e80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
13e90 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
13ea0 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
13eb0 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
13ec0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13ed0 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d  E_CONFIG_SMALL_M
13ee0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
13ef0 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f  TE_CONFIG_SMALL_
13f00 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
13f10 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13f20 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c  CONFIG_SMALL_MAL
13f30 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
13f40 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13f50 20 6f 66 0a 2a 2a 20 74 79 70 65 20 69 6e 74 2c   of.** type int,
13f60 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
13f70 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  a boolean, which
13f80 20 69 66 20 74 72 75 65 20 70 72 6f 76 69 64 65   if true provide
13f90 73 20 61 20 68 69 6e 74 20 74 6f 0a 2a 2a 20 53  s a hint to.** S
13fa0 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 73 68  QLite that it sh
13fb0 6f 75 6c 64 20 61 76 6f 69 64 20 6c 61 72 67 65  ould avoid large
13fc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13fd0 6f 6e 73 20 69 66 20 70 6f 73 73 69 62 6c 65 2e  ons if possible.
13fe0 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
13ff0 72 75 6e 20 66 61 73 74 65 72 20 69 66 20 69 74  run faster if it
14000 20 69 73 20 66 72 65 65 20 74 6f 20 6d 61 6b 65   is free to make
14010 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c   large memory al
14020 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a 2a 20 62 75  locations,.** bu
14030 74 20 73 6f 6d 65 20 61 70 70 6c 69 63 61 74 69  t some applicati
14040 6f 6e 20 6d 69 67 68 74 20 70 72 65 66 65 72 20  on might prefer 
14050 74 6f 20 72 75 6e 20 73 6c 6f 77 65 72 20 69 6e  to run slower in
14060 20 65 78 63 68 61 6e 67 65 20 66 6f 72 0a 2a 2a   exchange for.**
14070 20 67 75 61 72 61 6e 74 65 65 73 20 61 62 6f 75   guarantees abou
14080 74 20 6d 65 6d 6f 72 79 20 66 72 61 67 6d 65 6e  t memory fragmen
14090 74 61 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20  tation that are 
140a0 70 6f 73 73 69 62 6c 65 20 69 66 20 6c 61 72 67  possible if larg
140b0 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  e.** allocations
140c0 20 61 72 65 20 61 76 6f 69 64 65 64 2e 20 20 54   are avoided.  T
140d0 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 72 6d  his hint is norm
140e0 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a 20 3c 2f 64  ally off..** </d
140f0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14100 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
14110 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
14120 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
14130 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
14140 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14150 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f  _MEMSTATUS optio
14160 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
14170 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
14180 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65  int,.** interpre
14190 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
141a0 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
141b0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
141c0 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a  collection of.**
141d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
141e0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  on statistics. ^
141f0 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
14200 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
14210 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  cs are.** disabl
14220 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ed, the followin
14230 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
14240 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
14250 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
14260 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
14270 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
14280 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
14290 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
142a0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
142b0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
142c0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
142d0 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
142e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
142f0 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  64()].**   </ul>
14300 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
14310 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
14320 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
14330 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
14340 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
14350 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
14360 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
14370 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
14380 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
14390 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
143a0 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
143b0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
143c0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
143d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
143e0 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
143f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
14400 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
14410 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   The SQLITE_CONF
14420 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f  IG_SCRATCH optio
14430 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75  n is no longer u
14440 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  sed..** </dd>.**
14450 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14460 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
14470 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14480 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
14490 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
144a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
144b0 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65  CACHE option spe
144c0 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20  cifies a memory 
144d0 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c  pool.** that SQL
144e0 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
144f0 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
14500 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
14510 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a   default page.**
14520 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
14530 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
14540 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14550 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70  ption is a no-op
14560 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
14570 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
14580 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
14590 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
145a0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
145b0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
145c0 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  2]..** ^There ar
145d0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
145e0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
145f0 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20  IG_PAGECACHE: A 
14600 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d  pointer to.** 8-
14610 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d  byte aligned mem
14620 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20  ory (pMem), the 
14630 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67  size of each pag
14640 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a  e cache line (sz
14650 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75  ),.** and the nu
14660 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69  mber of cache li
14670 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  nes (N)..** The 
14680 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
14690 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
146a0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
146b0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
146c0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
146d0 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36  etween 512 and 6
146e0 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20  5536) plus some 
146f0 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20  extra bytes for 
14700 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
14710 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65  der.  ^The numbe
14720 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73  r of extra bytes
14730 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70   needed by the p
14740 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61  age header.** ca
14750 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
14760 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f  using [SQLITE_CO
14770 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
14780 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  Z]..** ^It is ha
14790 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
147a0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
147b0 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
147c0 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
147d0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
147e0 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
147f0 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  pMem.** argument
14800 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
14810 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
14820 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  r a pointer to a
14830 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
14840 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  ned block of mem
14850 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20  ory of at least 
14860 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65  sz*N bytes, othe
14870 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75  rwise.** subsequ
14880 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 20  ent behavior is 
14890 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57  undefined..** ^W
148a0 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20  hen pMem is not 
148b0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
148c0 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65 20  l strive to use 
148d0 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
148e0 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66  ded.** to satisf
148f0 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65 65  y page cache nee
14900 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b  ds, falling back
14910 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
14920 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70  loc()] if.** a p
14930 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69  age cache line i
14940 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a  s larger than sz
14950 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c   bytes or if all
14960 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66   of the pMem buf
14970 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73  fer.** is exhaus
14980 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d  ted..** ^If pMem
14990 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69   is NULL and N i
149a0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
149b0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
149c0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65  onnection.** doe
149d0 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c  s an initial bul
149e0 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  k allocation for
149f0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
14a00 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ry.** from [sqli
14a10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75  te3_malloc()] su
14a20 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63  fficient for N c
14a30 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20  ache lines if N 
14a40 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a  is positive or.*
14a50 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74  * of -1024*N byt
14a60 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74  es if N is negat
14a70 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74  ive, . ^If addit
14a80 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
14a90 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
14aa0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
14ab0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
14ac0 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61  the initial.** a
14ad0 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20  llocation, then 
14ae0 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b  SQLite goes to [
14af0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14b00 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72  ] separately for
14b10 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f   each.** additio
14b20 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20  nal cache line. 
14b30 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14b40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14b50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14b60 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a  NFIG_HEAP</dt>.*
14b70 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
14b80 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
14b90 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
14ba0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
14bb0 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20  buffer .** that 
14bc0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
14bd0 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
14be0 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c  ynamic memory al
14bf0 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a  location needs.*
14c00 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  * beyond those p
14c10 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b  rovided for by [
14c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
14c30 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68  GECACHE]..** ^Th
14c40 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14c50 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f  HEAP option is o
14c60 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
14c70 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14c80 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68  led.** with eith
14c90 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
14ca0 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53  E_MEMSYS3] or [S
14cb0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
14cc0 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e  SYS5] and return
14cd0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  s.** [SQLITE_ERR
14ce0 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f  OR] if invoked o
14cf0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68  therwise..** ^Th
14d00 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
14d10 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
14d20 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a  E_CONFIG_HEAP:.*
14d30 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  * An 8-byte alig
14d40 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
14d50 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
14d60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
14d70 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
14d80 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
14d90 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
14da0 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
14db0 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
14dc0 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
14dd0 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
14de0 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
14df0 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
14e00 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
14e10 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
14e20 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
14e30 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
14e40 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
14e50 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
14e60 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
14e70 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
14e80 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
14e90 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
14ea0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c  NULL then the al
14eb0 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
14ec0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
14ed0 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
14ee0 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
14ef0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
14f00 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
14f10 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
14f20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
14f30 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
14f40 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
14f50 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
14f60 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
14f70 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
14f80 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
14f90 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
14fa0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
14fb0 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
14fc0 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
14fd0 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
14fe0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
14ff0 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
15000 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
15010 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15020 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
15030 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
15040 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
15050 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
15060 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
15070 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
15080 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
15090 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20  t which is a.** 
150a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
150b0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
150c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
150d0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
150e0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
150f0 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72   specifies alter
15100 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
15110 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
15120 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e  to be used.** in
15130 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78   place the mutex
15140 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
15150 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
15160 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
15170 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
15180 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
15190 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
151a0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
151b0 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
151c0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
151d0 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
151e0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
151f0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
15200 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
15210 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
15220 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
15230 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15240 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
15250 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
15260 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
15270 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
15280 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
15290 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
152a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
152b0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
152c0 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
152d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
152e0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
152f0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
15300 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15310 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
15320 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15330 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
15340 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
15350 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15360 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  ETMUTEX option t
15370 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
15380 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
15390 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
153a0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
153b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
153c0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
153d0 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
153e0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
153f0 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
15400 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
15410 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
15420 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
15430 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
15440 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
15450 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
15460 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
15470 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
15480 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
15490 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
154a0 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
154b0 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
154c0 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
154d0 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
154e0 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
154f0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
15500 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
15510 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
15520 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
15530 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
15540 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
15550 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
15560 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
15570 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
15580 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
15590 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
155a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
155b0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
155c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
155d0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
155e0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
155f0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
15600 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
15610 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15620 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
15630 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15640 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
15650 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
15660 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
15670 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61  KASIDE option ta
15680 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
15690 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
156a0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
156b0 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  size of lookasid
156c0 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68  e memory on each
156d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
156e0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
156f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
15700 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
15710 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
15720 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
15730 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
15740 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
15750 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
15760 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
15770 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
15780 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15790 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20  OKASIDE.** sets 
157a0 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  the <i>default</
157b0 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
157c0 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
157d0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
157e0 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20  E].** option to 
157f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
15800 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
15810 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
15820 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
15830 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
15840 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
15850 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
15860 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15870 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
15880 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15890 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
158a0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
158b0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
158c0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
158d0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
158e0 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
158f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
15900 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
15910 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
15920 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
15930 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74  ifies.** the int
15940 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74  erface to a cust
15950 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
15960 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a  plementation.)^.
15970 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ** ^SQLite makes
15980 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
15990 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
159a0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
159b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
159c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
159d0 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
159e0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
159f0 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
15a00 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
15a10 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15a20 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
15a30 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
15a40 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
15a50 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
15a60 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
15a70 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
15a80 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
15a90 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
15aa0 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
15ab0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
15ac0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
15ad0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15ae0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
15af0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15b00 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
15b10 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
15b20 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
15b30 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
15b40 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
15b50 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
15b60 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
15b70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15b80 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
15b90 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
15ba0 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
15bb0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
15bc0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
15bd0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
15be0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
15bf0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
15c00 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
15c10 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
15c20 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
15c30 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
15c40 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
15c50 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
15c60 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
15c70 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
15c80 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
15c90 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
15ca0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
15cb0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
15cc0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
15cd0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
15ce0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
15cf0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
15d00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
15d10 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
15d20 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
15d30 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
15d40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
15d50 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
15d60 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
15d70 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
15d80 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
15d90 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
15da0 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
15db0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
15dc0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
15dd0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
15de0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
15df0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
15e00 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
15e10 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
15e20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
15e30 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
15e40 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
15e50 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
15e60 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
15e70 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
15e80 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
15e90 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
15ea0 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
15eb0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
15ec0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
15ed0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
15ee0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
15ef0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
15f00 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
15f10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
15f20 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
15f30 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
15f40 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
15f50 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
15f60 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
15f70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
15f80 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
15f90 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
15fa0 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
15fb0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15fc0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
15fd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
15fe0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  I.** <dd>^(The S
15ff0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
16000 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
16010 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
16020 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20  of type int..** 
16030 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
16040 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
16050 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
16060 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
16070 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  eter is zero,.**
16080 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
16090 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ng is globally d
160a0 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
160b0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
160c0 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c  lobally.** enabl
160d0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
160e0 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
160f0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
16100 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
16110 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
16120 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
16130 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
16140 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
16150 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
16160 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
16170 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
16180 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
16190 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
161a0 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
161b0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
161c0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
161d0 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
161e0 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
161f0 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
16200 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
16210 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
16220 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
16230 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
16240 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
16250 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
16260 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
16270 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
16280 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
16290 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
162a0 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
162b0 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
162c0 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
162d0 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
162e0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
162f0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
16300 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
16310 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
16320 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
16330 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16340 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
16350 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  CAN.** <dd>^The 
16360 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
16370 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
16380 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  N option takes a
16390 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a   single integer.
163a0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ** argument whic
163b0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
163c0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e   as a boolean in
163d0 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
163e0 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   or disable.** t
163f0 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
16400 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
16410 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
16420 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
16430 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  imizer..** ^The 
16440 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
16450 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
16460 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
16470 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
16480 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
16490 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
164a0 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
164b0 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
164c0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
164d0 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
164e0 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
164f0 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
16500 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
16510 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
16520 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
16530 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
16540 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
16550 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
16560 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
16570 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
16580 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
16590 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
165a0 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
165b0 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
165c0 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
165d0 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
165e0 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
165f0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
16600 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
16610 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
16620 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
16630 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16640 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
16650 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16660 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
16670 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16680 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
16690 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
166a0 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
166b0 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
166c0 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
166d0 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
166e0 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
166f0 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
16700 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
16710 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
16720 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
16730 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16740 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
16750 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
16760 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
16770 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
16780 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
16790 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
167a0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
167b0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
167c0 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
167d0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
167e0 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
167f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
16800 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
16810 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
16820 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
16830 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
16840 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
16850 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
16860 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
16870 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
16880 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
16890 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
168a0 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
168b0 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
168c0 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
168d0 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
168e0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
168f0 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
16900 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
16910 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
16920 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
16930 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
16940 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
16950 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
16960 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
16970 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
16980 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
16990 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
169a0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
169b0 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
169c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
169d0 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
169e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
169f0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
16a00 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
16a10 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
16a20 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
16a30 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
16a40 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
16a50 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
16a60 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
16a70 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
16a80 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
16a90 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16aa0 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
16ab0 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
16ac0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
16ad0 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
16ae0 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
16af0 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
16b00 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
16b10 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
16b20 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
16b30 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
16b40 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
16b50 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
16b60 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
16b70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
16b90 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
16ba0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
16bb0 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
16bc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
16bd0 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
16be0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
16bf0 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
16c00 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
16c10 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
16c20 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
16c30 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
16c40 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
16c50 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
16c60 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
16c70 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
16c80 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
16c90 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
16ca0 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
16cb0 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
16cc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
16cd0 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
16ce0 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
16cf0 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
16d00 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
16d10 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
16d20 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
16d30 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
16d40 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
16d50 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c  map size.** will
16d60 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75   be silently tru
16d70 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73  ncated if necess
16d80 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64  ary so that it d
16d90 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74  oes not exceed t
16da0 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  he.** compile-ti
16db0 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
16dc0 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
16dd0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
16de0 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
16df0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
16e00 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
16e10 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
16e20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
16e30 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
16e40 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
16e50 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
16e60 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
16e70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
16e80 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
16e90 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
16ea0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
16eb0 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
16ec0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
16ed0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
16ee0 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20  PSIZE option is 
16ef0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
16f00 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  f SQLite is.** c
16f10 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
16f20 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
16f30 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
16f40 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
16f50 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65   macro.** define
16f60 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  d. ^SQLITE_CONFI
16f70 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
16f80 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
16f90 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
16fa0 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
16fb0 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
16fc0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
16fd0 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
16fe0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16ff0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
17000 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
17010 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
17020 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  HDRSZ.** <dd>^Th
17030 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17040 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74  PCACHE_HDRSZ opt
17050 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
17060 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
17070 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
17080 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
17090 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f   and writes into
170a0 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68   that integer th
170b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
170c0 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70  a.** bytes per p
170d0 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72  age required for
170e0 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53   each page in [S
170f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
17100 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20  ECACHE]..** The 
17110 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20  amount of extra 
17120 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63  space required c
17130 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64  an change depend
17140 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  ing on the compi
17150 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70  ler,.** target p
17160 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c  latform, and SQL
17170 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a  ite version..**.
17180 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17190 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64  IG_PMASZ]].** <d
171a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
171b0 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PMASZ.** <dd>^Th
171c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
171d0 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  PMASZ option tak
171e0 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
171f0 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
17200 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e  s an unsigned in
17210 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74  teger and sets t
17220 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20  he "Minimum PMA 
17230 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75  Size" for the mu
17240 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73  ltithreaded.** s
17250 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  orter to that in
17260 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61  teger.  The defa
17270 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20  ult minimum PMA 
17280 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74  Size is set by t
17290 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  he.** [SQLITE_SO
172a0 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70  RTER_PMASZ] comp
172b0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
172c0 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72    New threads ar
172d0 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f  e launched.** to
172e0 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20   help with sort 
172f0 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20  operations when 
17300 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f  multithreaded so
17310 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62  rting.** is enab
17320 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b  led (using the [
17330 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20  PRAGMA threads] 
17340 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65  command) and the
17350 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
17360 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74  nt.** to be sort
17370 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70  ed exceeds the p
17380 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74  age size times t
17390 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68  he minimum of th
173a0 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63  e.** [PRAGMA cac
173b0 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67  he_size] setting
173c0 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e   and this value.
173d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
173e0 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
173f0 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  SPILL]].** <dt>S
17400 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
17410 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c  TJRNL_SPILL.** <
17420 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
17430 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
17440 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65  PILL option take
17450 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
17460 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65  eter which.** be
17470 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65  comes the [state
17480 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70  ment journal] sp
17490 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65  ill-to-disk thre
174a0 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61  shold.  .** [Sta
174b0 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d  tement journals]
174c0 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d   are held in mem
174d0 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20  ory until their 
174e0 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a  size (in bytes).
174f0 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20  ** exceeds this 
17500 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68  threshold, at wh
17510 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61  ich point they a
17520 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  re written to di
17530 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65  sk..** Or if the
17540 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31   threshold is -1
17550 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  , statement jour
17560 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20  nals are always 
17570 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76  held.** exclusiv
17580 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a  ely in memory..*
17590 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61  * Since many sta
175a0 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20  tement journals 
175b0 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72  never become lar
175c0 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20  ge, setting the 
175d0 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f  spill.** thresho
175e0 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75  ld to a value su
175f0 63 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20  ch as 64KiB can 
17600 67 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74  greatly reduce t
17610 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20  he amount of.** 
17620 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20  I/O required to 
17630 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e  support statemen
17640 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  t rollback..** T
17650 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
17660 20 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e   for this settin
17670 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  g is controlled 
17680 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
17690 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  E_STMTJRNL_SPILL
176a0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
176b0 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  ption..** </dl>.
176c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
176d0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
176e0 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
176f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17700 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
17710 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
17720 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
17730 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
17740 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
17750 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
17760 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
17770 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
17780 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
17790 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
177a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
177b0 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
177c0 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
177d0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
177e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
177f0 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
17800 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
17810 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
17820 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
17830 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
17840 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
17850 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
17860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
17870 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
17880 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
17890 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
178a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
178b0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
178c0 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
178d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
178e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
178f0 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
17900 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
17910 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
17920 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
17930 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
17940 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
17950 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
17960 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
17970 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
17980 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
17990 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
179a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
179b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
179c0 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
179d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
179e0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
179f0 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
17a00 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
17a10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17a20 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
17a30 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
17a40 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17a50 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
17a60 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
17a70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17a80 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
17a90 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
17aa0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
17ab0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17ac0 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
17ad0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
17ae0 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
17af0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17b00 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
17b10 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
17b20 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
17b30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17b40 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
17b50 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
17b60 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
17b70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17b80 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
17b90 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
17ba0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17bb0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
17bc0 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73  SIZE    22  /* s
17bd0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71  qlite3_int64, sq
17be0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23  lite3_int64 */.#
17bf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17c00 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
17c10 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20  IZE      23  /* 
17c20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
17c30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17c40 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
17c50 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e         24  /* in
17c60 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e  t *psz */.#defin
17c70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17c80 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20  PMASZ           
17c90 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67      25  /* unsig
17ca0 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f  ned int szPma */
17cb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17cc0 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
17cd0 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f  SPILL      26  /
17ce0 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
17cf0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17d00 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f  NFIG_SMALL_MALLO
17d10 43 20 20 20 20 20 20 20 20 32 37 20 20 2f 2a 20  C        27  /* 
17d20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 0a 2f 2a 0a 2a  boolean */../*.*
17d30 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
17d40 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
17d50 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
17d60 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
17d70 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
17d80 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
17d90 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
17da0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
17db0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
17dc0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
17dd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
17de0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17df0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
17e00 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
17e10 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
17e20 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
17e30 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
17e40 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
17e50 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
17e60 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
17e70 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
17e80 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
17e90 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
17ea0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
17eb0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
17ec0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
17ed0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
17ee0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
17ef0 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
17f00 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17f10 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
17f20 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
17f30 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
17f40 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
17f50 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
17f60 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
17f70 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
17f80 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
17f90 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
17fa0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
17fb0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
17fc0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
17fd0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
17fe0 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
17ff0 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
18000 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
18010 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
18020 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
18030 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
18040 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
18050 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
18060 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
18070 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
18080 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
18090 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
180a0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
180b0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
180c0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
180d0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
180e0 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
180f0 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
18100 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
18110 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
18120 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
18130 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
18140 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
18150 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
18160 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
18170 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
18180 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18190 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
181a0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
181b0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
181c0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
181d0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
181e0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
181f0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
18200 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
18210 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
18220 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
18230 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
18240 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
18250 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
18260 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
18270 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
18280 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
18290 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
182a0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
182b0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
182c0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
182d0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
182e0 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
182f0 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
18300 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
18310 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
18320 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
18330 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
18340 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
18350 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
18360 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
18370 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18380 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
18390 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
183a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
183b0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
183c0 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
183d0 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
183e0 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
183f0 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
18400 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
18410 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
18420 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
18430 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
18440 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
18450 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
18460 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
18470 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
18480 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
18490 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
184a0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
184b0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
184c0 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
184d0 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
184e0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
184f0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
18500 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
18510 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
18520 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
18530 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
18540 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
18550 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
18560 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
18570 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
18580 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
18590 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
185a0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
185b0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
185c0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
185d0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
185e0 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
185f0 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
18600 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
18610 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
18620 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
18630 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
18640 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
18650 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
18660 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
18670 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
18680 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
18690 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
186a0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
186b0 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
186c0 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
186d0 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
186e0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
186f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18700 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
18710 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
18720 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
18730 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
18740 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
18750 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
18760 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
18770 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18780 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
18790 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
187a0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
187b0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
187c0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
187d0 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
187e0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
187f0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
18800 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
18810 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18820 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
18830 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
18840 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
18850 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
18860 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
18870 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
18880 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
18890 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
188a0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
188b0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
188c0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
188d0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
188e0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
188f0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
18900 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
18910 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
18920 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
18930 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
18940 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
18950 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
18960 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
18970 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
18980 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
18990 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
189a0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
189b0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
189c0 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b  _ENABLE_FTS3_TOK
189d0 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENIZER</dt>.** <
189e0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
189f0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
18a00 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
18a10 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a  e two-argument.*
18a20 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  * version of the
18a30 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72   [fts3_tokenizer
18a40 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69  ()] function whi
18a50 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  ch is part of th
18a60 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c  e.** [FTS3] full
18a70 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67  -text search eng
18a80 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a  ine extension..*
18a90 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
18aa0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18ab0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
18ac0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18ad0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
18ae0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
18af0 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  sable fts3_token
18b00 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73  izer() or.** pos
18b10 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
18b20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
18b30 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
18b40 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
18b50 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a  g.** unchanged..
18b60 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
18b70 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
18b80 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
18b90 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
18ba0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
18bb0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
18bc0 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65  hether fts3_toke
18bd0 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  nizer is disable
18be0 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
18bf0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
18c00 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
18c10 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
18c20 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
18c30 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
18c40 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
18c50 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
18c60 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
18c70 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18c80 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18c90 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f  LOAD_EXTENSION</
18ca0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
18cb0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
18cc0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
18cd0 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  sable the [sqlit
18ce0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
18cf0 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  n()].** interfac
18d00 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20  e independently 
18d10 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74  of the [load_ext
18d20 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75  ension()] SQL fu
18d30 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b  nction..** The [
18d40 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
18d50 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18d60 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20   API enables or 
18d70 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68  disables both th
18d80 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69  e.** C-API [sqli
18d90 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
18da0 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51  on()] and the SQ
18db0 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64  L function [load
18dc0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a  _extension()]..*
18dd0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
18de0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18df0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57   arguments..** W
18e00 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72  hen the first ar
18e10 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69  gument to this i
18e20 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74  nterface is 1, t
18e30 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41  hen only the C-A
18e40 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64  PI is.** enabled
18e50 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
18e60 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69  ction remains di
18e70 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20  sabled.  If the 
18e80 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
18e90 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66  o.** this interf
18ea0 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62  ace is 0, then b
18eb0 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e  oth the C-API an
18ec0 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
18ed0 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e  on are disabled.
18ee0 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74  .** If the first
18ef0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c   argument is -1,
18f00 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73   then no changes
18f10 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61   are made to sta
18f20 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65  te of either the
18f30 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65  .** C-API or the
18f40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
18f50 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
18f60 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
18f70 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
18f80 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
18f90 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
18fa0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
18fb0 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c  ether [sqlite3_l
18fc0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18fd0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
18fe0 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
18ff0 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  bled following t
19000 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
19010 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19020 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c  may.** be a NULL
19030 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69   pointer, in whi
19040 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20  ch case the new 
19050 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
19060 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a  eported back..**
19070 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
19080 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
19090 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e  _MAINDBNAME</dt>
190a0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
190b0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
190c0 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65   change the name
190d0 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64   of the "main" d
190e0 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d  atabase.** schem
190f0 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72  a.  ^The sole ar
19100 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
19110 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e  ter to a constan
19120 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a  t UTF8 string.**
19130 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f   which will beco
19140 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d  me the new schem
19150 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20  a name in place 
19160 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c  of "main".  ^SQL
19170 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ite.** does not 
19180 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
19190 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65  he new main sche
191a0 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20  ma name string, 
191b0 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  so the applicati
191c0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72  on.** must ensur
191d0 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d  e that the argum
191e0 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ent passed into 
191f0 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70  this DBCONFIG op
19200 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65  tion is unchange
19210 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72  d.** until after
19220 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
19230 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
19240 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
19250 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
19260 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43  FIG_NO_CKPT_ON_C
19270 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LOSE</dt>.** <dd
19280 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20  > Usually, when 
19290 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 61  a database in wa
192a0 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64  l mode is closed
192b0 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 6f   or detached fro
192c0 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  m a .** database
192d0 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20   handle, SQLite 
192e0 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 77  checks if this w
192f0 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68  ill mean that th
19300 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a  ere are now no .
19310 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61  ** connections a
19320 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74  t all to the dat
19330 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74  abase. If so, it
19340 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63   performs a chec
19350 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61  kpoint .** opera
19360 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73  tion before clos
19370 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  ing the connecti
19380 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  on. This option 
19390 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a  may be used to.*
193a0 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20  * override this 
193b0 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66  behaviour. The f
193c0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70  irst parameter p
193d0 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70  assed to this op
193e0 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e  eration.** is an
193f0 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d 7a   integer - non-z
19400 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 63  ero to disable c
19410 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c  heckpoints-on-cl
19420 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68  ose, or zero (th
19430 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f  e.** default) to
19440 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54 68   enable them. Th
19450 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19460 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
19470 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
19480 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77   into which is w
19490 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
194a0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
194b0 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e  r checkpoints-on
194c0 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62  -close.** have b
194d0 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30  een disabled - 0
194e0 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74   if they are not
194f0 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20   disabled, 1 if 
19500 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64  they are..** </d
19510 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
19520 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
19530 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a 2a  BLE_QPSG</dt>.**
19540 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54   <dd>^(The SQLIT
19550 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
19560 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20 61 63  E_QPSG option ac
19570 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74  tivates or deact
19580 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 5b 71  ivates.** the [q
19590 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 73 74 61  uery planner sta
195a0 62 69 6c 69 74 79 20 67 75 61 72 61 6e 74 65 65  bility guarantee
195b0 5d 20 28 51 50 53 47 29 2e 20 20 57 68 65 6e 20  ] (QPSG).  When 
195c0 74 68 65 20 51 50 53 47 20 69 73 20 61 63 74 69  the QPSG is acti
195d0 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20  ve,.** a single 
195e0 53 51 4c 20 71 75 65 72 79 20 73 74 61 74 65 6d  SQL query statem
195f0 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ent will always 
19600 75 73 65 20 74 68 65 20 73 61 6d 65 20 61 6c 67  use the same alg
19610 6f 72 69 74 68 6d 20 72 65 67 61 72 64 6c 65 73  orithm regardles
19620 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73 20 6f  s.** of values o
19630 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
19640 65 72 73 5d 2e 29 5e 20 54 68 65 20 51 50 53 47  ers].)^ The QPSG
19650 20 64 69 73 61 62 6c 65 73 20 73 6f 6d 65 20 71   disables some q
19660 75 65 72 79 20 6f 70 74 69 6d 69 7a 61 74 69 6f  uery optimizatio
19670 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b 20  ns.** that look 
19680 61 74 20 74 68 65 20 76 61 6c 75 65 73 20 6f 66  at the values of
19690 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72   bound parameter
196a0 73 2c 20 77 68 69 63 68 20 63 61 6e 20 6d 61 6b  s, which can mak
196b0 65 20 73 6f 6d 65 20 71 75 65 72 69 65 73 0a 2a  e some queries.*
196c0 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75 74 20 74  * slower.  But t
196d0 68 65 20 51 50 53 47 20 68 61 73 20 74 68 65 20  he QPSG has the 
196e0 61 64 76 61 6e 74 61 67 65 20 6f 66 20 6d 6f 72  advantage of mor
196f0 65 20 70 72 65 64 69 63 74 61 62 6c 65 20 62 65  e predictable be
19700 68 61 76 69 6f 72 2e 20 20 57 69 74 68 0a 2a 2a  havior.  With.**
19710 20 74 68 65 20 51 50 53 47 20 61 63 74 69 76 65   the QPSG active
19720 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  , SQLite will al
19730 77 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d  ways use the sam
19740 65 20 71 75 65 72 79 20 70 6c 61 6e 20 69 6e 20  e query plan in 
19750 74 68 65 20 66 69 65 6c 64 20 61 73 0a 2a 2a 20  the field as.** 
19760 77 61 73 20 75 73 65 64 20 64 75 72 69 6e 67 20  was used during 
19770 74 65 73 74 69 6e 67 20 69 6e 20 74 68 65 20 6c  testing in the l
19780 61 62 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ab..** </dd>.**.
19790 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
197a0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
197b0 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20  FIG_MAINDBNAME  
197c0 20 20 20 20 20 20 20 20 20 20 31 30 30 30 20 2f            1000 /
197d0 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f  * const char* */
197e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
197f0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
19800 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31  DE             1
19810 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  001 /* void* int
19820 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
19830 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19840 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
19850 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e        1002 /* in
19860 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
19870 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
19880 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
19890 20 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20          1003 /* 
198a0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
198b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
198c0 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f  FIG_ENABLE_FTS3_
198d0 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f  TOKENIZER 1004 /
198e0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
198f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
19900 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41  ONFIG_ENABLE_LOA
19910 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35  D_EXTENSION 1005
19920 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
19930 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19940 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
19950 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31 30  ON_CLOSE      10
19960 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  06 /* int int* *
19970 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19980 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19990 5f 51 50 53 47 20 20 20 20 20 20 20 20 20 20 20  _QPSG           
199a0 31 30 30 37 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1007 /* int int*
199b0 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   */.../*.** CAPI
199c0 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
199d0 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
199e0 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
199f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
19a00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19a10 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
19a20 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
19a30 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
19a40 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
19a50 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
19a60 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
19a70 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
19a80 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
19a90 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
19aa0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
19ab0 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
19ac0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
19ad0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
19ae0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
19af0 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
19b00 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
19b10 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
19b20 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d  nsert Rowid.** M
19b30 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
19b40 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
19b50 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20   in most SQLite 
19b60 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66  tables (except f
19b70 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  or [WITHOUT ROWI
19b80 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61  D] tables).** ha
19b90 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
19ba0 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
19bb0 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
19bc0 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
19bd0 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
19be0 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
19bf0 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
19c00 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
19c10 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
19c20 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
19c30 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
19c40 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
19c50 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
19c60 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
19c70 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
19c80 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
19c90 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
19ca0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
19cb0 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
19cc0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
19cd0 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
19ce0 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
19cf0 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  The sqlite3_last
19d00 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
19d10 20 69 6e 74 65 72 66 61 63 65 20 75 73 75 61 6c   interface usual
19d20 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ly returns the [
19d30 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20 74 68 65  rowid] of.** the
19d40 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
19d50 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
19d60 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61   into a rowid ta
19d70 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ble or [virtual 
19d80 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74  table].** on dat
19d90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19da0 20 44 2e 20 5e 49 6e 73 65 72 74 73 20 69 6e 74   D. ^Inserts int
19db0 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  o [WITHOUT ROWID
19dc0 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74  ] tables are not
19dd0 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e 20 5e 49  .** recorded. ^I
19de0 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
19df0 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72  [INSERT]s into r
19e00 6f 77 69 64 20 74 61 62 6c 65 73 20 68 61 76 65  owid tables have
19e10 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 0a   ever occurred .
19e20 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ** on the databa
19e30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c  se connection D,
19e40 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61   then sqlite3_la
19e50 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
19e60 44 29 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 7a  D) returns .** z
19e70 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65  ero..**.** As we
19e80 6c 6c 20 61 73 20 62 65 69 6e 67 20 73 65 74 20  ll as being set 
19e90 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 73  automatically as
19ea0 20 72 6f 77 73 20 61 72 65 20 69 6e 73 65 72 74   rows are insert
19eb0 65 64 20 69 6e 74 6f 20 64 61 74 61 62 61 73 65  ed into database
19ec0 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74 68 65 20  .** tables, the 
19ed0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
19ee0 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  y this function 
19ef0 6d 61 79 20 62 65 20 73 65 74 20 65 78 70 6c 69  may be set expli
19f00 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b 73 71 6c  citly by.** [sql
19f10 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
19f20 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
19f30 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74 75 61 6c  .** Some virtual
19f40 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
19f50 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e 53 45 52  ations may INSER
19f60 54 20 72 6f 77 73 20 69 6e 74 6f 20 72 6f 77 69  T rows into rowi
19f70 64 20 74 61 62 6c 65 73 20 61 73 0a 2a 2a 20 70  d tables as.** p
19f80 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74 74 69 6e  art of committin
19f90 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
19fa0 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73 68 20 64  (e.g. to flush d
19fb0 61 74 61 20 61 63 63 75 6d 75 6c 61 74 65 64 20  ata accumulated 
19fc0 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20  in memory.** to 
19fd0 64 69 73 6b 29 2e 20 49 6e 20 74 68 69 73 20 63  disk). In this c
19fe0 61 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 63  ase subsequent c
19ff0 61 6c 6c 73 20 74 6f 20 74 68 69 73 20 66 75 6e  alls to this fun
1a000 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 74 68 65  ction return the
1a010 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73 6f 63 69   rowid.** associ
1a020 61 74 65 64 20 77 69 74 68 20 74 68 65 73 65 20  ated with these 
1a030 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45 52 54 20  internal INSERT 
1a040 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68 69 63  operations, whic
1a050 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a 2a 20 75  h leads to .** u
1a060 6e 69 6e 74 75 69 74 69 76 65 20 72 65 73 75 6c  nintuitive resul
1a070 74 73 2e 20 56 69 72 74 75 61 6c 20 74 61 62 6c  ts. Virtual tabl
1a080 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1a090 73 20 74 68 61 74 20 64 6f 20 77 72 69 74 65 20  s that do write 
1a0a0 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74 61 62 6c  to rowid.** tabl
1a0b0 65 73 20 69 6e 20 74 68 69 73 20 77 61 79 20 63  es in this way c
1a0c0 61 6e 20 61 76 6f 69 64 20 74 68 69 73 20 70 72  an avoid this pr
1a0d0 6f 62 6c 65 6d 20 62 79 20 72 65 73 74 6f 72 69  oblem by restori
1a0e0 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ng the original 
1a0f0 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c 75 65 20  .** rowid value 
1a100 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
1a110 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  et_last_insert_r
1a120 6f 77 69 64 28 29 5d 20 62 65 66 6f 72 65 20 72  owid()] before r
1a130 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e  eturning .** con
1a140 74 72 6f 6c 20 74 6f 20 74 68 65 20 75 73 65 72  trol to the user
1a150 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
1a160 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
1a170 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
1a180 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
1a190 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72 65 74 75  ne will .** retu
1a1a0 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
1a1b0 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 20 72  f the inserted r
1a1c0 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
1a1d0 65 20 74 72 69 67 67 65 72 20 69 73 20 0a 2a 2a  e trigger is .**
1a1e0 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65 20 74   running. Once t
1a1f0 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  he trigger progr
1a200 61 6d 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  am ends, the val
1a210 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
1a220 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
1a230 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
1a240 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
1a250 65 20 74 72 69 67 67 65 72 20 77 61 73 20 66 69  e trigger was fi
1a260 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  red.)^.**.** ^An
1a270 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
1a280 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
1a290 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
1a2a0 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
1a2b0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
1a2c0 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
1a2d0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
1a2e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
1a2f0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
1a300 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
1a310 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
1a320 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
1a330 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
1a340 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
1a350 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
1a360 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
1a370 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
1a380 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
1a390 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
1a3a0 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
1a3b0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
1a3c0 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
1a3d0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
1a3e0 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
1a3f0 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
1a400 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
1a410 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
1a420 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
1a430 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
1a440 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
1a450 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
1a460 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
1a470 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
1a480 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
1a490 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
1a4a0 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
1a4b0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
1a4c0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
1a4d0 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
1a4e0 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
1a4f0 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
1a500 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
1a510 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
1a520 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
1a530 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
1a540 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
1a550 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
1a560 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
1a570 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
1a580 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1a590 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1a5a0 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
1a5b0 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
1a5c0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
1a5d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a5e0 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
1a5f0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1a600 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
1a610 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
1a620 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
1a630 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
1a640 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
1a650 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
1a660 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1a670 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1a680 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
1a690 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
1a6a0 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
1a6b0 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
1a6c0 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
1a6d0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
1a6e0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  */.sqlite3_int64
1a6f0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
1a700 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
1a710 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1a720 49 33 52 45 46 3a 20 53 65 74 20 74 68 65 20 4c  I3REF: Set the L
1a730 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
1a740 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45 54 48 4f   value..** METHO
1a750 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1a760 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   The sqlite3_set
1a770 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1a780 69 64 28 44 2c 20 52 29 20 6d 65 74 68 6f 64 20  id(D, R) method 
1a790 61 6c 6c 6f 77 73 20 74 68 65 20 61 70 70 6c 69  allows the appli
1a7a0 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 73 65 74  cation to.** set
1a7b0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a7c0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 73  ned by calling s
1a7d0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1a7e0 72 74 5f 72 6f 77 69 64 28 44 29 20 74 6f 20 52  rt_rowid(D) to R
1a7f0 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20 69 6e 73   .** without ins
1a800 65 72 74 69 6e 67 20 61 20 72 6f 77 20 69 6e 74  erting a row int
1a810 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a  o the database..
1a820 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1a830 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
1a840 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 2c 73  rowid(sqlite3*,s
1a850 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
1a860 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a870 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
1a880 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
1a890 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
1a8a0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1a8b0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1a8c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1a8d0 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69  rows modified, i
1a8e0 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65  nserted or.** de
1a8f0 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73  leted by the mos
1a900 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
1a910 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
1a920 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  ATE or DELETE.**
1a930 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68   statement on th
1a940 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a950 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20  ction specified 
1a960 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  by the only para
1a970 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75  meter..** ^Execu
1a980 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74  ting any other t
1a990 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ype of SQL state
1a9a0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f  ment does not mo
1a9b0 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a  dify the value.*
1a9c0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  * returned by th
1a9d0 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  is function..**.
1a9e0 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ** ^Only changes
1a9f0 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62   made directly b
1aa00 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50  y the INSERT, UP
1aa10 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1aa20 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20  tatement are.** 
1aa30 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78  considered - aux
1aa40 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
1aa50 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45  aused by [CREATE
1aa60 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
1aa70 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69  ers], .** [forei
1aa80 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
1aa90 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  or [REPLACE] con
1aaa0 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
1aab0 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  on are not count
1aac0 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67  ed..** .** Chang
1aad0 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
1aae0 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
1aaf0 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41  d by .** [INSTEA
1ab00 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49  D OF trigger | I
1ab10 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1ab20 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  rs] are not coun
1ab30 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20  ted. ^The value 
1ab40 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
1ab50 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1ab60 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66  ) immediately af
1ab70 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55  ter an INSERT, U
1ab80 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c  PDATE or .** DEL
1ab90 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75  ETE statement ru
1aba0 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61  n on a view is a
1abb0 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79  lways zero. Only
1abc0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f   changes made to
1abd0 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73   real .** tables
1abe0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
1abf0 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d  .** Things are m
1ac00 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20  ore complicated 
1ac10 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  if the sqlite3_c
1ac20 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
1ac30 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64  n is.** executed
1ac40 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72   while a trigger
1ac50 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e   program is runn
1ac60 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61  ing. This may ha
1ac70 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70  ppen if the.** p
1ac80 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20  rogram uses the 
1ac90 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
1aca0 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20  unction], or if 
1acb0 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62  some other callb
1acc0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
1acd0 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f  invokes sqlite3_
1ace0 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74  changes() direct
1acf0 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a  ly. Essentially:
1ad00 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  .** .** <ul>.** 
1ad10 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20    <li> ^(Before 
1ad20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67  entering a trigg
1ad30 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76  er program the v
1ad40 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1ad50 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74  .**        sqlit
1ad60 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  e3_changes() fun
1ad70 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20  ction is saved. 
1ad80 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65  After the trigge
1ad90 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20  r program .**   
1ada0 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65       has finishe
1adb0 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  d, the original 
1adc0 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65  value is restore
1add0 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c  d.)^.** .**   <l
1ade0 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72  i> ^(Within a tr
1adf0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61  igger program ea
1ae00 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ch INSERT, UPDAT
1ae10 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a  E and DELETE .**
1ae20 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e          statemen
1ae30 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65  t sets the value
1ae40 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1ae50 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
1ae60 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63  **        upon c
1ae70 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72  ompletion as nor
1ae80 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20  mal. Of course, 
1ae90 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20  this value will 
1aea0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20  not include .** 
1aeb0 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67         any chang
1aec0 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  es performed by 
1aed0 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73  sub-triggers, as
1aee0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
1aef0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
1af00 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20    value will be 
1af10 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72  saved and restor
1af20 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75  ed after each su
1af30 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75  b-trigger has ru
1af40 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  n.)^.** </ul>.**
1af50 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73   .** ^This means
1af60 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61   that if the cha
1af70 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1af80 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29  ion (or similar)
1af90 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74   is used.** by t
1afa0 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c  he first INSERT,
1afb0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1afc0 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1afd0 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74  in a trigger, it
1afe0 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65   .** returns the
1aff0 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68   value as set wh
1b000 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73  en the calling s
1b010 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65  tatement began e
1b020 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66  xecuting..** ^If
1b030 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74   it is used by t
1b040 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62  he second or sub
1b050 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61  sequent such sta
1b060 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20  tement within a 
1b070 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67  trigger .** prog
1b080 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72  ram, the value r
1b090 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73  eturned reflects
1b0a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
1b0b0 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20  ows modified by 
1b0c0 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73  the .** previous
1b0d0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1b0e0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1b0f0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73  ent within the s
1b100 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a  ame trigger..**.
1b110 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
1b120 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1b130 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
1b140 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
1b150 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
1b160 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61  a], and the [cha
1b170 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1b180 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
1b190 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1b1a0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
1b1b0 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
1b1c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1b1d0 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
1b1e0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
1b1f0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
1b200 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
1b210 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  * is unpredictab
1b220 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
1b230 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
1b240 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71  lite3_changes(sq
1b250 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1b260 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20  CAPI3REF: Total 
1b270 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
1b280 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
1b290 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1b2a0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1b2b0 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61  returns the tota
1b2c0 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  l number of rows
1b2d0 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66   inserted, modif
1b2e0 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ied or.** delete
1b2f0 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54  d by all [INSERT
1b300 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ], [UPDATE] or [
1b310 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
1b320 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20  ts completed.** 
1b330 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61  since the databa
1b340 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61  se connection wa
1b350 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64  s opened, includ
1b360 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74  ing those execut
1b370 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
1b380 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1b390 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e  s. ^Executing an
1b3a0 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20  y other type of 
1b3b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
1b3c0 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74   does not affect
1b3d0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1b3e0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  ned by sqlite3_t
1b3f0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a  otal_changes()..
1b400 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20  ** .** ^Changes 
1b410 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
1b420 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
1b430 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64  ions] are includ
1b440 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75  ed in the.** cou
1b450 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61  nt, but those ma
1b460 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45  de as part of RE
1b470 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74  PLACE constraint
1b480 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a   resolution are.
1b490 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73  ** not. ^Changes
1b4a0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
1b4b0 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20  are intercepted 
1b4c0 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72  by INSTEAD OF tr
1b4d0 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e  iggers .** are n
1b4e0 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
1b4f0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
1b500 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
1b510 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
1b520 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
1b530 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
1b540 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61  d the [total_cha
1b550 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1b560 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
1b570 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1b580 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
1b590 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
1b5a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1b5b0 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
1b5c0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1b5d0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
1b5e0 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
1b5f0 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
1b600 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
1b610 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
1b620 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  int sqlite3_tota
1b630 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  l_changes(sqlite
1b640 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1b650 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20  3REF: Interrupt 
1b660 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51  A Long-Running Q
1b670 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  uery.** METHOD: 
1b680 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1b690 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
1b6a0 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
1b6b0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1b6c0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
1b6d0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
1b6e0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
1b6f0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
1b700 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
1b710 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
1b720 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
1b730 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
1b740 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
1b750 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
1b760 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
1b770 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
1b780 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
1b790 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
1b7a0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
1b7b0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
1b7c0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
1b7d0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
1b7e0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
1b7f0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
1b800 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
1b810 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
1b820 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
1b830 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
1b840 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
1b850 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
1b860 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1b870 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
1b880 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
1b890 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
1b8a0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
1b8b0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
1b8c0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
1b8d0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
1b8e0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
1b8f0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
1b900 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1b910 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
1b920 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
1b930 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
1b940 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
1b950 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
1b960 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
1b970 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
1b980 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
1b990 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
1b9a0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
1b9b0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
1b9c0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
1b9d0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
1b9e0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
1b9f0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
1ba00 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
1ba10 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
1ba20 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
1ba30 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
1ba40 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
1ba50 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
1ba60 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
1ba70 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
1ba80 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1ba90 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
1baa0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
1bab0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
1bac0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
1bad0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
1bae0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1baf0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
1bb00 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
1bb10 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1bb20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1bb30 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1bb40 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
1bb50 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
1bb60 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
1bb70 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
1bb80 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
1bb90 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
1bba0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
1bbb0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
1bbc0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1bbd0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
1bbe0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1bbf0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1bc00 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
1bc10 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
1bc20 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
1bc30 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
1bc40 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
1bc50 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
1bc60 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
1bc70 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
1bc80 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
1bc90 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
1bca0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
1bcb0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
1bcc0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
1bcd0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
1bce0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1bcf0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1bd00 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1bd10 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
1bd20 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  urns..*/.void sq
1bd30 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1bd40 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1bd50 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
1bd60 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
1bd70 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d  Statement Is Com
1bd80 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73  plete.**.** Thes
1bd90 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
1bda0 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d  seful during com
1bdb0 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20  mand-line input 
1bdc0 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20  to determine if 
1bdd0 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79  the.** currently
1bde0 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65   entered text se
1bdf0 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f  ems to form a co
1be00 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1be10 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64  ment or.** if ad
1be20 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69  ditional input i
1be30 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20  s needed before 
1be40 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74  sending the text
1be50 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20   into.** SQLite 
1be60 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54  for parsing.  ^T
1be70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1be80 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
1be90 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
1bea0 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
1beb0 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
1bec0 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d  ment.  ^A statem
1bed0 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f  ent is judged to
1bee0 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20   be.** complete 
1bef0 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20  if it ends with 
1bf00 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65  a semicolon toke
1bf10 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  n and is not a p
1bf20 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65  refix of a.** we
1bf30 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45  ll-formed CREATE
1bf40 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65   TRIGGER stateme
1bf50 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73  nt.  ^Semicolons
1bf60 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64   that are embedd
1bf70 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72  ed within.** str
1bf80 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20  ing literals or 
1bf90 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65  quoted identifie
1bfa0 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65  r names or comme
1bfb0 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69  nts are not.** i
1bfc0 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e  ndependent token
1bfd0 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74  s (they are part
1bfe0 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e   of the token in
1bff0 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a   which they are.
1c000 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64  ** embedded) and
1c010 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75   thus do not cou
1c020 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e  nt as a statemen
1c030 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  t terminator.  ^
1c040 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
1c050 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
1c060 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
1c070 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
1c080 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gnored..**.** ^T
1c090 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
1c0a0 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74  turn 0 if the st
1c0b0 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d  atement is incom
1c0c0 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a  plete.  ^If a.**
1c0d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1c0e0 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53  on fails, then S
1c0f0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72  QLITE_NOMEM is r
1c100 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
1c110 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64  These routines d
1c120 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20  o not parse the 
1c130 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74  SQL statements t
1c140 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20  hus.** will not 
1c150 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63  detect syntactic
1c160 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53  ally incorrect S
1c170 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  QL..**.** ^(If S
1c180 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65  QLite has not be
1c190 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75  en initialized u
1c1a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e  sing [sqlite3_in
1c1b0 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f  itialize()] prio
1c1c0 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e  r .** to invokin
1c1d0 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  g sqlite3_comple
1c1e0 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69  te16() then sqli
1c1f0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1c200 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1c210 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
1c220 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1c230 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69  16().  If that i
1c240 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61  nitialization fa
1c250 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ils,.** then the
1c260 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
1c270 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  om sqlite3_compl
1c280 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20  ete16() will be 
1c290 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61  non-zero.** rega
1c2a0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1c2b0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70  r or not the inp
1c2c0 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65  ut SQL is comple
1c2d0 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te.)^.**.** The 
1c2e0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1c2f0 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75  3_complete()] mu
1c300 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1c310 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38  minated.** UTF-8
1c320 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
1c330 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1c340 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1c350 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1c360 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1c370 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
1c380 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1c390 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
1c3a0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
1c3b0 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e  t char *sql);.in
1c3c0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
1c3d0 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
1c3e0 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
1c3f0 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
1c400 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
1c410 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
1c420 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57  Y Errors.** KEYW
1c430 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64  ORDS: {busy-hand
1c440 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62  ler callback} {b
1c450 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20  usy handler}.** 
1c460 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1c470 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c480 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1c490 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73  D,X,P) routine s
1c4a0 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
1c4b0 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61  unction X.** tha
1c4c0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
1c4d0 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
1c4e0 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61   P whenever.** a
1c4f0 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
1c500 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61  e to access a da
1c510 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73  tabase table ass
1c520 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
1c530 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c540 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f  tion] D when ano
1c550 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
1c560 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68  r process has th
1c570 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a  e table locked..
1c580 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
1c590 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e  usy_handler() in
1c5a0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
1c5b0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20  to implement.** 
1c5c0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
1c5d0 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52  meout()] and [PR
1c5e0 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1c5f0 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  t]..**.** ^If th
1c600 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
1c610 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
1c620 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69  QLITE_BUSY].** i
1c630 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
1c640 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
1c650 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
1c660 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
1c670 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1c680 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
1c690 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
1c6a0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
1c6b0 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
1c6c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1c6d0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
1c6e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
1c6f0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1c700 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
1c710 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
1c720 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
1c730 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1c740 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
1c750 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
1c760 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1c770 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
1c780 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
1c790 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
1c7a0 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
1c7b0 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70  * been invoked p
1c7c0 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68  reviously for th
1c7d0 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65  e same locking e
1c7e0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
1c7f0 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
1c800 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
1c810 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
1c820 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
1c830 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
1c840 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
1c850 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72  QLITE_BUSY] is r
1c860 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68  eturned.** to th
1c870 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a  e application..*
1c880 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
1c890 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1c8a0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
1c8b0 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
1c8c0 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74  made to access t
1c8d0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1c8e0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
1c8f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
1c900 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
1c910 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
1c920 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
1c930 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
1c940 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
1c950 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
1c960 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
1c970 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
1c980 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
1c990 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
1c9a0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
1c9b0 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
1c9c0 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
1c9d0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
1c9e0 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  Y].** to the app
1c9f0 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64  lication instead
1ca00 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
1ca10 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65   .** busy handle
1ca20 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
1ca30 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
1ca40 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
1ca50 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
1ca60 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
1ca70 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
1ca80 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
1ca90 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
1caa0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
1cab0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
1cac0 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
1cad0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
1cae0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
1caf0 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
1cb00 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
1cb10 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
1cb20 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
1cb30 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1cb40 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
1cb50 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
1cb60 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
1cb70 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1cb80 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
1cb90 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
1cba0 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
1cbb0 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
1cbc0 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
1cbd0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
1cbe0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
1cbf0 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
1cc00 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
1cc10 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
1cc20 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
1cc30 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
1cc40 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
1cc50 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
1cc60 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
1cc70 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
1cc80 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1cc90 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
1cca0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1ccb0 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
1ccc0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
1ccd0 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1cce0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1ccf0 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
1cd00 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
1cd10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cd20 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
1cd30 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
1cd40 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
1cd50 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
1cd60 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
1cd70 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
1cd80 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1cd90 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75  t()].** or evalu
1cda0 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75  ating [PRAGMA bu
1cdb0 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69  sy_timeout=N] wi
1cdc0 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  ll change the.**
1cdd0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e   busy handler an
1cde0 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79  d thus clear any
1cdf0 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1ce00 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1ce10 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
1ce20 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
1ce30 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
1ce40 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
1ce50 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
1ce60 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1ce70 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1ce80 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68  handler.  In oth
1ce90 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65  er words,.** the
1cea0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1ceb0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20   not reentrant. 
1cec0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
1ced0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
1cee0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
1cef0 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
1cf00 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
1cf10 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
1cf20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1cf30 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
1cf40 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1cf50 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1cf60 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
1cf70 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1cf80 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69  ndler(sqlite3*,i
1cf90 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
1cfa0 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ,void*);../*.** 
1cfb0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
1cfc0 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20  Busy Timeout.** 
1cfd0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1cfe0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1cff0 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
1d000 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1d010 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
1d020 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
1d030 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
1d040 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
1d050 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
1d060 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
1d070 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
1d080 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
1d090 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
1d0a0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1d0b0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
1d0c0 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
1d0d0 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
1d0e0 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1d0f0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1d100 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
1d110 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
1d120 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
1d130 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
1d140 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
1d150 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  BUSY]..**.** ^Ca
1d160 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
1d170 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
1d180 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
1d190 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
1d1a0 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
1d1b0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
1d1c0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1d1d0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1d1e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
1d1f0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
1d200 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1d210 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20  nection] at any 
1d220 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
1d230 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
1d240 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
1d250 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
1d260 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1d270 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
1d280 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
1d290 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
1d2a0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1d2b0 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
1d2c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1d2d0 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1d2e0 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71  meout].*/.int sq
1d2f0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1d300 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
1d310 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
1d320 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
1d330 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
1d340 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
1d350 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1d360 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e3.**.** This is
1d370 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
1d380 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
1d390 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
1d3a0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1d3b0 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
1d3c0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
1d3d0 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
1d3e0 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
1d3f0 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
1d400 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
1d410 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
1d420 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
1d430 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
1d440 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
1d450 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
1d460 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
1d470 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
1d480 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
1d490 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
1d4a0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
1d4b0 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
1d4c0 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
1d4d0 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
1d4e0 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
1d4f0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
1d500 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
1d510 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
1d520 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
1d530 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
1d540 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
1d550 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
1d560 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
1d570 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
1d580 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
1d590 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1d5a0 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
1d5b0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
1d5c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1d5d0 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
1d5e0 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
1d5f0 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
1d600 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
1d610 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
1d620 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
1d630 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1d640 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
1d650 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
1d660 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
1d670 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
1d680 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
1d690 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
1d6a0 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
1d6b0 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
1d6c0 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
1d6d0 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
1d6e0 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
1d6f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1d700 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
1d710 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
1d720 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
1d730 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
1d740 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1d750 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
1d760 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
1d770 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d780 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
1d790 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
1d7a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
1d7b0 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
1d7c0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
1d7d0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
1d7e0 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
1d7f0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1d800 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
1d810 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
1d820 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
1d830 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
1d840 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
1d850 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
1d860 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1d870 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1d880 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
1d890 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
1d8a0 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
1d8b0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1d8c0 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
1d8d0 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
1d8e0 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
1d8f0 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
1d900 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
1d910 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
1d920 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1d930 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
1d940 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
1d950 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
1d960 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
1d970 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
1d980 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
1d990 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
1d9a0 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
1d9b0 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
1d9c0 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
1d9d0 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
1d9e0 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
1d9f0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1da00 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1da10 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1da20 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
1da30 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1da40 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
1da50 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1da60 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
1da70 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
1da80 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
1da90 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
1daa0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
1dab0 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
1dac0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1dad0 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
1dae0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1daf0 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
1db00 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1db10 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
1db20 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
1db30 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
1db40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1db50 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
1db60 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
1db70 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
1db80 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
1db90 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
1dba0 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
1dbb0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
1dbc0 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
1dbd0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
1dbe0 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
1dbf0 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
1dc00 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
1dc10 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
1dc20 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
1dc30 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
1dc40 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
1dc50 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
1dc60 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
1dc70 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
1dc80 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
1dc90 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
1dca0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
1dcb0 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
1dcc0 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
1dcd0 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
1dce0 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
1dcf0 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
1dd00 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
1dd10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
1dd20 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
1dd30 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1dd40 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
1dd50 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
1dd60 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
1dd70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
1dd80 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
1dd90 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
1dda0 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
1ddb0 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
1ddc0 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
1ddd0 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
1dde0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
1ddf0 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
1de00 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
1de10 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
1de20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
1de30 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
1de40 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1de50 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
1de60 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
1de70 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
1de80 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
1de90 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
1dea0 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
1deb0 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
1dec0 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
1ded0 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
1dee0 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
1def0 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
1df00 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
1df10 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1df20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
1df30 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
1df40 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
1df50 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
1df60 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
1df70 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
1df80 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
1df90 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  rmsg()]..*/.int 
1dfa0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1dfb0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1dfc0 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
1dfd0 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
1dfe0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1dff0 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
1e000 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
1e010 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
1e020 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
1e030 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
1e040 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
1e050 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
1e060 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1e070 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
1e080 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
1e090 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
1e0a0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1e0b0 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
1e0c0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
1e0d0 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
1e0e0 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
1e0f0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1e100 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
1e110 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
1e120 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
1e130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
1e140 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
1e150 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
1e160 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1e170 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
1e180 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
1e190 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
1e1a0 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
1e1b0 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
1e1c0 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54   C library..** T
1e1d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e  hese routines un
1e1e0 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66  derstand most of
1e1f0 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20   the common K&R 
1e200 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1e210 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65  ns,.** plus some
1e220 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d   additional non-
1e230 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73  standard formats
1e240 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77  , detailed below
1e250 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73  ..** Note that s
1e260 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20  ome of the more 
1e270 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69  obscure formatti
1e280 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20  ng options from 
1e290 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72  recent.** C-libr
1e2a0 61 72 79 20 73 74 61 6e 64 61 72 64 73 20 61 72  ary standards ar
1e2b0 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
1e2c0 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  his implementati
1e2d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
1e2e0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
1e2f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
1e300 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
1e310 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
1e320 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
1e330 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
1e340 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
1e350 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
1e360 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1e370 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
1e380 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
1e390 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
1e3a0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
1e3b0 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
1e3c0 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
1e3d0 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
1e3e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
1e3f0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1e400 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
1e410 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1e420 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
1e430 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
1e440 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1e450 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
1e460 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
1e470 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
1e480 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1e490 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
1e4a0 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
1e4b0 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
1e4c0 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
1e4d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1e4e0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
1e4f0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
1e500 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
1e510 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
1e520 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
1e530 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
1e540 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
1e550 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
1e560 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
1e570 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
1e580 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
1e590 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
1e5a0 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
1e5b0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1e5c0 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
1e5d0 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
1e5e0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
1e5f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1e600 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
1e610 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
1e620 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
1e630 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
1e640 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
1e650 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
1e660 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
1e670 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1e680 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
1e690 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
1e6a0 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
1e6b0 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
1e6c0 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
1e6d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
1e6e0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1e6f0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
1e700 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
1e710 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
1e720 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
1e730 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
1e740 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
1e750 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1e760 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
1e770 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
1e780 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
1e790 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
1e7a0 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1e7b0 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
1e7c0 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
1e7d0 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
1e7e0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
1e7f0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1e800 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
1e810 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
1e820 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
1e830 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
1e840 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
1e850 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
1e860 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
1e870 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1e880 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
1e890 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1e8a0 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
1e8b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1e8c0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d  ll implement som
1e8d0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72  e additional for
1e8e0 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f  matting.** optio
1e8f0 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66  ns that are usef
1e900 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74  ul for construct
1e910 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ing SQL statemen
1e920 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68  ts..** All of th
1e930 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29  e usual printf()
1e940 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1e950 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61  ons apply.  In a
1e960 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a  ddition, there.*
1e970 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22  * is are "%q", "
1e980 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25  %Q", "%w" and "%
1e990 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  z" options..**.*
1e9a0 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f  * ^(The %q optio
1e9b0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20  n works like %s 
1e9c0 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74  in that it subst
1e9d0 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72  itutes a nul-ter
1e9e0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1e9f0 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
1ea00 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
1ea10 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
1ea20 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
1ea30 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
1ea40 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
1ea50 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
1ea60 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f  iteral.)^  By do
1ea70 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
1ea80 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
1ea90 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
1eaa0 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
1eab0 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
1eac0 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
1ead0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
1eae0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
1eaf0 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
1eb00 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
1eb10 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
1eb20 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1eb30 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1eb40 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
1eb50 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
1eb60 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
1eb70 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1eb80 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
1eb90 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
1eba0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
1ebb0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1ebc0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1ebd0 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1ebe0 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1ebf0 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1ec00 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
1ec10 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
1ec20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
1ec30 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
1ec40 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
1ec50 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
1ec60 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1ec70 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
1ec80 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
1ec90 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
1eca0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
1ecb0 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
1ecc0 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
1ecd0 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
1ece0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1ecf0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1ed00 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
1ed10 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
1ed20 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
1ed30 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
1ed40 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1ed50 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
1ed60 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
1ed70 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
1ed80 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
1ed90 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
1eda0 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
1edb0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
1edc0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1edd0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1ede0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1edf0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1ee00 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1ee10 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1ee20 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
1ee30 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
1ee40 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
1ee50 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
1ee60 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
1ee70 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
1ee80 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
1ee90 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
1eea0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1eeb0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  l..**.** ^(The %
1eec0 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
1eed0 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
1eee0 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
1eef0 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
1ef00 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
1ef10 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
1ef20 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
1ef30 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
1ef40 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
1ef50 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
1ef60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
1ef70 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
1ef80 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
1ef90 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
1efa0 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c   quotes).)^  So,
1efb0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
1efc0 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
1efd0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1efe0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1eff0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1f000 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1f010 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1f020 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
1f030 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
1f040 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
1f050 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
1f060 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
1f070 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1f080 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
1f090 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
1f0a0 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
1f0b0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
1f0c0 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
1f0d0 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
1f0e0 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
1f0f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1f100 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77  .**.** ^(The "%w
1f110 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
1f120 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22  ion is like "%q"
1f130 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1f140 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65  expects to.** be
1f150 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69   contained withi
1f160 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20  n double-quotes 
1f170 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c  instead of singl
1f180 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74  e quotes, and it
1f190 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65 20  .** escapes the 
1f1a0 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61  double-quote cha
1f1b0 72 61 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f  racter instead o
1f1c0 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f  f the single-quo
1f1d0 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e  te.** character.
1f1e0 29 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f 72  )^  The "%w" for
1f1f0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1f200 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73  s intended for s
1f210 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a  afely inserting.
1f220 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  ** table and col
1f230 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61  umn names into a
1f240 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c   constructed SQL
1f250 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
1f260 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72  * ^(The "%z" for
1f270 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77  matting option w
1f280 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62  orks like "%s" b
1f290 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61  ut with the.** a
1f2a0 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74  ddition that aft
1f2b0 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61  er the string ha
1f2c0 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20  s been read and 
1f2d0 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74  copied into.** t
1f2e0 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69  he result, [sqli
1f2f0 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63  te3_free()] is c
1f300 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70  alled on the inp
1f310 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a  ut string.)^.*/.
1f320 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70  char *sqlite3_mp
1f330 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1f340 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71  *,...);.char *sq
1f350 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63  lite3_vmprintf(c
1f360 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
1f370 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ist);.char *sqli
1f380 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74  te3_snprintf(int
1f390 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1f3a0 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  r*, ...);.char *
1f3b0 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1f3c0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1f3d0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1f3e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f3f0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1f400 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
1f410 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
1f420 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
1f430 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
1f440 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
1f450 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
1f460 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f470 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
1f480 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
1f490 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
1f4a0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
1f4b0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
1f4c0 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
1f4d0 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
1f4e0 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
1f4f0 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
1f500 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
1f510 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
1f520 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1f530 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1f540 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1f550 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
1f560 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
1f570 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1f580 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
1f590 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
1f5a0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
1f5b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1f5c0 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
1f5d0 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
1f5e0 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
1f5f0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1f600 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
1f610 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
1f620 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1f630 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
1f640 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
1f650 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1f660 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
1f670 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1f680 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
1f690 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65  loc64(N) routine
1f6a0 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65   works just like
1f6b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1f6c0 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74 68 61  oc(N) except tha
1f6d0 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e  t N is an unsign
1f6e0 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  ed 64-bit intege
1f6f0 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  r instead.** of 
1f700 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20  a signed 32-bit 
1f710 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  integer..**.** ^
1f720 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
1f730 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
1f740 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
1f750 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1f760 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f770 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
1f780 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
1f790 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
1f7a0 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
1f7b0 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20  e reused.  ^The 
1f7c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72  sqlite3_free() r
1f7d0 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e  outine is.** a n
1f7e0 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65  o-op if is calle
1f7f0 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
1f800 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20  inter.  Passing 
1f810 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
1f820 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  * to sqlite3_fre
1f830 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  e() is harmless.
1f840 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72    After being fr
1f850 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73  eed, memory.** s
1f860 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65  hould neither be
1f870 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65   read nor writte
1f880 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67  n.  Even reading
1f890 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65   previously free
1f8a0 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68  d.** memory migh
1f8b0 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65  t result in a se
1f8c0 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1f8d0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1f8e0 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72   error..** Memor
1f8f0 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20  y corruption, a 
1f900 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1f910 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76  lt, or other sev
1f920 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67  ere error.** mig
1f930 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c  ht result if sql
1f940 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63  ite3_free() is c
1f950 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e  alled with a non
1f960 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68  -NULL pointer th
1f970 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62  at.** was not ob
1f980 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
1f990 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1f9a0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f9b0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
1f9c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1f9d0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  N) interface att
1f9e0 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20  empts to resize 
1f9f0 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72  a.** prior memor
1fa00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74  y allocation X t
1fa10 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20  o be at least N 
1fa20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
1fa30 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e X parameter to
1fa40 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1fa50 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55  (X,N).** is a NU
1fa60 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1fa70 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
1fa80 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
1fa90 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1faa0 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49  malloc(N)..** ^I
1fab0 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  f the N paramete
1fac0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1fad0 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72  lloc(X,N) is zer
1fae0 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65  o or.** negative
1faf0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1fb00 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  or is exactly th
1fb10 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e  e same as callin
1fb20 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  g.** sqlite3_fre
1fb30 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65  e(X)..** ^sqlite
1fb40 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
1fb50 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1fb60 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   to a memory all
1fb70 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74  ocation.** of at
1fb80 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1fb90 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69  n size or NULL i
1fba0 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d  f insufficient m
1fbb0 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62  emory is availab
1fbc0 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20  le..** ^If M is 
1fbd0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
1fbe0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1fbf0 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
1fc00 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
1fc10 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1fc20 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
1fc30 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
1fc40 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
1fc50 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1fc60 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64  realloc(X,N) and
1fc70 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1fc80 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
1fc90 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
1fca0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1fcb0 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69  rns NULL and N i
1fcc0 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e  s positive, then
1fcd0 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c   the.** prior al
1fce0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  location is not 
1fcf0 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
1fd00 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1fd10 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61  c64(X,N) interfa
1fd20 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61  ces works the sa
1fd30 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33  me as.** sqlite3
1fd40 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78  _realloc(X,N) ex
1fd50 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61  cept that N is a
1fd60 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   64-bit unsigned
1fd70 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64   integer instead
1fd80 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20  .** of a 32-bit 
1fd90 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a  signed integer..
1fda0 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61  **.** ^If X is a
1fdb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1fdc0 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  on previously ob
1fdd0 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
1fde0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  te3_malloc(),.**
1fdf0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1fe00 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61  4(), sqlite3_rea
1fe10 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74  lloc(), or sqlit
1fe20 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20  e3_realloc64(), 
1fe30 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
1fe40 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73  msize(X) returns
1fe50 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61   the size of tha
1fe60 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
1fe70 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a  ion in bytes..**
1fe80 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
1fe90 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1fea0 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62  msize(X) might b
1feb0 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  e larger than th
1fec0 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62  e number.** of b
1fed0 79 74 65 73 20 72 65 71 75 65 73 74 65 64 20 77  ytes requested w
1fee0 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61  hen X was alloca
1fef0 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61  ted.  ^If X is a
1ff00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
1ff10 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1ff20 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a  ize(X) returns z
1ff30 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74  ero.  If X point
1ff40 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74  s to something t
1ff50 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68  hat is not.** th
1ff60 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d  e beginning of m
1ff70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ff80 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74  , or if it point
1ff90 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a  s to a formerly.
1ffa0 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20  ** valid memory 
1ffb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20  allocation that 
1ffc0 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65  has now been fre
1ffd0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ed, then the beh
1ffe0 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69  avior.** of sqli
1fff0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20  te3_msize(X) is 
20000 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f  undefined and po
20010 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  ssibly harmful..
20020 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
20030 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
20040 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20  lite3_malloc(), 
20050 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
20060 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ),.** sqlite3_ma
20070 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71  lloc64(), and sq
20080 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
20090 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
200a0 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
200b0 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
200c0 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a  ndary, or to a.*
200d0 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72  * 4 byte boundar
200e0 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  y if the [SQLITE
200f0 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f  _4_BYTE_ALIGNED_
20100 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d  MALLOC] compile-
20110 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69  time.** option i
20120 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  s used..**.** In
20130 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
20140 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
20150 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
20160 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
20170 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
20180 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
20190 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
201a0 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
201b0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
201c0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
201d0 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
201e0 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
201f0 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
20200 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
20210 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
20220 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
20230 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
20240 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
20250 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c   version 3.7.10,
20260 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   the Windows OS 
20270 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
20280 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79  called.** the sy
20290 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
202a0 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
202b0 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
202c0 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
202d0 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
202e0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
202f0 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
20300 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
20310 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
20320 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
20330 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
20340 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
20350 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
20360 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74   errors were det
20370 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
20380 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64  ey were reported
20390 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
203a0 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
203b0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
203c0 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
203d0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
203e0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72  * The pointer ar
203f0 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
20400 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
20410 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
20420 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  ()].** must be e
20430 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
20440 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
20450 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
20460 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20  r.** invocation 
20470 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
20480 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
20490 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
204a0 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65  t have.** not ye
204b0 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e  t been released.
204c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
204d0 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
204e0 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e  read or write an
204f0 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62  y part of.** a b
20500 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
20510 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
20520 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
20530 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
20540 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
20550 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76  realloc()]..*/.v
20560 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
20570 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a  loc(int);.void *
20580 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
20590 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  (sqlite3_uint64)
205a0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
205b0 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
205c0 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
205d0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69  e3_realloc64(voi
205e0 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
205f0 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
20600 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73  3_free(void*);.s
20610 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71  qlite3_uint64 sq
20620 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64  lite3_msize(void
20630 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
20640 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
20650 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
20660 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
20670 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
20680 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
20690 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
206a0 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
206b0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
206c0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
206d0 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
206e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
206f0 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
20700 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
20710 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
20720 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
20730 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
20740 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
20750 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
20760 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
20770 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
20780 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
20790 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
207a0 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
207b0 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
207c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
207d0 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
207e0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
207f0 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
20800 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
20810 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
20820 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
20830 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
20840 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
20850 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
20860 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20870 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
20880 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
20890 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
208a0 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
208b0 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
208c0 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
208d0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
208e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
208f0 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
20900 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
20910 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
20920 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
20930 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
20940 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
20950 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
20960 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
20970 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
20980 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
20990 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
209a0 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
209b0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
209c0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
209d0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
209e0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
209f0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
20a00 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
20a10 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
20a20 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20a30 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
20a40 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
20a50 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
20a60 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
20a70 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
20a80 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
20a90 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33  d(void);.sqlite3
20aa0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
20ab0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
20ac0 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
20ad0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20ae0 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
20af0 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a  umber Generator.
20b00 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e  **.** SQLite con
20b10 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61  tains a high-qua
20b20 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64  lity pseudo-rand
20b30 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61  om number genera
20b40 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20  tor (PRNG) used 
20b50 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e  to.** select ran
20b60 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57  dom [ROWID | ROW
20b70 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74  IDs] when insert
20b80 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20  ing new records 
20b90 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61  into a table tha
20ba0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65  t.** already use
20bb0 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f  s the largest po
20bc0 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20  ssible [ROWID]. 
20bd0 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73   The PRNG is als
20be0 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68  o used for.** th
20bf0 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f  e build-in rando
20c00 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c  m() and randombl
20c10 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ob() SQL functio
20c20 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66  ns.  This interf
20c30 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70  ace allows.** ap
20c40 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63  plications to ac
20c50 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52  cess the same PR
20c60 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72  NG for other pur
20c70 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  poses..**.** ^A 
20c80 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
20c90 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
20ca0 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
20cb0 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
20cc0 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d  .** ^The P param
20cd0 65 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55  eter can be a NU
20ce0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
20cf0 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69  * ^If this routi
20d00 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  ne has not been 
20d10 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65  previously calle
20d20 64 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 76  d or if the prev
20d30 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64  ious.** call had
20d40 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65   N less than one
20d50 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
20d60 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74  er for P, then t
20d70 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65  he PRNG is.** se
20d80 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
20d90 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66  mness obtained f
20da0 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
20db0 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a  ess method of.**
20dc0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
20dd0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
20de0 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  t..** ^If the pr
20df0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74  evious call to t
20e00 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20  his routine had 
20e10 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72  an N of 1 or mor
20e20 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e  e and a.** non-N
20e30 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70  ULL P then the p
20e40 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
20e50 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
20e60 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
20e70 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
20e80 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
20e90 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
20ea0 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  s.** method..*/.
20eb0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
20ec0 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
20ed0 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
20ee0 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
20ef0 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
20f00 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
20f10 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
20f20 33 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  3.** KEYWORDS: {
20f30 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20f40 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ack}.**.** ^This
20f50 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
20f60 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
20f70 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
20f80 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
20f90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20fa0 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
20fb0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
20fc0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
20fd0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20fe0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
20ff0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
21000 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
21010 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
21020 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
21030 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
21040 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21050 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
21060 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b  prepare_v3()], [
21070 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
21080 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70  6()], [sqlite3_p
21090 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a  repare16_v2()],.
210a0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
210b0 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 2e  prepare16_v3()].
210c0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
210d0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
210e0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
210f0 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
21100 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
21110 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
21120 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
21130 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21140 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
21150 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
21160 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
21170 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
21180 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21190 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
211a0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
211b0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
211c0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
211d0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
211e0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
211f0 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
21200 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
21210 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
21220 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
21230 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
21240 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
21250 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
21260 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
21270 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
21280 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
21290 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
212a0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
212b0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
212c0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
212d0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
212e0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
212f0 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
21300 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
21310 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
21320 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
21330 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
21340 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
21350 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
21360 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
21370 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
21380 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
21390 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
213a0 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
213b0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
213c0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
213d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
213e0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
213f0 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
21400 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21410 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
21420 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
21430 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
21440 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
21450 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
21460 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
21470 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
21480 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
21490 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
214a0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
214b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
214c0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
214d0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
214e0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
214f0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
21500 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
21510 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
21520 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
21530 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
21540 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
21550 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
21560 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
21570 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
21580 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
21590 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
215a0 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
215b0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
215c0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
215d0 61 63 6b 20 61 72 65 20 65 69 74 68 65 72 20 4e  ack are either N
215e0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6f 72 20  ULL pointers or 
215f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
21600 73 74 72 69 6e 67 73 0a 2a 2a 20 74 68 61 74 20  strings.** that 
21610 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e  contain addition
21620 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  al details about
21630 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
21640 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
21650 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75   Applications mu
21660 73 74 20 61 6c 77 61 79 73 20 62 65 20 70 72 65  st always be pre
21670 70 61 72 65 64 20 74 6f 20 65 6e 63 6f 75 6e 74  pared to encount
21680 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
21690 72 20 69 6e 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  r in any.** of t
216a0 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
216b0 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d   the sixth param
216c0 65 74 65 72 73 20 6f 66 20 74 68 65 20 61 75 74  eters of the aut
216d0 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62  horization callb
216e0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ack..**.** ^If t
216f0 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
21700 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
21710 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
21720 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
21730 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
21740 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
21750 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
21760 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
21770 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
21780 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
21790 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
217a0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
217b0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
217c0 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
217d0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
217e0 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
217f0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
21800 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
21810 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
21820 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
21830 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
21840 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
21850 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
21860 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 74 61 62 6c  .** ^When a tabl
21870 65 20 69 73 20 72 65 66 65 72 65 6e 63 65 64 20  e is referenced 
21880 62 79 20 61 20 5b 53 45 4c 45 43 54 5d 20 62 75  by a [SELECT] bu
21890 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  t no column valu
218a0 65 73 20 61 72 65 0a 2a 2a 20 65 78 74 72 61 63  es are.** extrac
218b0 74 65 64 20 66 72 6f 6d 20 74 68 61 74 20 74 61  ted from that ta
218c0 62 6c 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ble (for example
218d0 20 69 6e 20 61 20 71 75 65 72 79 20 6c 69 6b 65   in a query like
218e0 0a 2a 2a 20 22 53 45 4c 45 43 54 20 63 6f 75 6e  .** "SELECT coun
218f0 74 28 2a 29 20 46 52 4f 4d 20 74 61 62 22 29 20  t(*) FROM tab") 
21900 74 68 65 6e 20 74 68 65 20 5b 53 51 4c 49 54 45  then the [SQLITE
21910 5f 52 45 41 44 5d 20 61 75 74 68 6f 72 69 7a 65  _READ] authorize
21920 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
21930 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f   invoked once fo
21940 72 20 74 68 61 74 20 74 61 62 6c 65 20 77 69 74  r that table wit
21950 68 20 61 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20  h a column name 
21960 74 68 61 74 20 69 73 20 61 6e 20 65 6d 70 74 79  that is an empty
21970 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
21980 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
21990 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
219a0 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
219b0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
219c0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
219d0 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
219e0 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
219f0 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
21a00 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
21a10 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
21a20 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
21a30 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
21a40 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
21a50 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
21a60 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
21a70 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
21a80 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
21a90 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
21aa0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
21ab0 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
21ac0 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
21ad0 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
21ae0 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
21af0 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
21b00 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
21b10 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
21b20 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
21b30 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
21b40 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
21b50 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
21b60 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
21b70 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
21b80 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
21b90 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
21ba0 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
21bb0 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
21bc0 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
21bd0 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
21be0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
21bf0 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
21c00 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
21c10 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
21c20 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
21c30 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
21c40 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
21c50 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
21c60 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
21c70 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
21c80 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
21c90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21ca0 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
21cb0 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
21cc0 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
21cd0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
21ce0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
21cf0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
21d00 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
21d10 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
21d20 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
21d30 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
21d40 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
21d50 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
21d60 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
21d70 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
21d80 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
21d90 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
21da0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
21db0 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
21dc0 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
21dd0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
21de0 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
21df0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
21e00 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
21e10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21e20 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
21e30 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
21e40 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21e50 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
21e60 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
21e70 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
21e80 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
21e90 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
21ea0 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
21eb0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
21ec0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
21ed0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
21ee0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
21ef0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
21f00 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
21f10 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
21f20 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
21f30 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
21f40 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
21f50 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
21f60 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
21f70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21f80 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
21f90 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
21fa0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
21fb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21fc0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
21fd0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
21fe0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
21ff0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
22000 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22010 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
22020 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
22030 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
22040 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
22050 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
22060 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
22070 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
22080 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
22090 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
220a0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
220b0 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
220c0 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
220d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
220e0 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
220f0 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
22100 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
22110 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
22120 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22130 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
22140 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
22150 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
22160 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
22170 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
22180 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
22190 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
221a0 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
221b0 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
221c0 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
221d0 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
221e0 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
221f0 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
22200 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
22210 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
22220 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
22230 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
22240 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
22250 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nge..*/.int sqli
22260 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
22270 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
22280 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
22290 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
222a0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
222b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
222c0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
222d0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
222e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
222f0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
22300 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
22310 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
22320 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
22330 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
22340 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
22350 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
22360 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
22370 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
22380 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
22390 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
223a0 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
223b0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
223c0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
223d0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
223e0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
223f0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
22400 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
22410 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
22420 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
22430 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
22440 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20  QLITE_IGNORE is 
22450 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b  also used as a [
22460 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74  conflict resolut
22470 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74  ion mode].** ret
22480 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b  urned from the [
22490 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
224a0 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65  conflict()] inte
224b0 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
224c0 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
224d0 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
224e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
224f0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
22500 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
22510 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
22520 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
22530 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
22540 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
22550 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22560 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
22570 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
22580 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
22590 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
225a0 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
225b0 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
225c0 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
225d0 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
225e0 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
225f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
22600 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
22610 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
22620 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
22630 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
22640 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
22650 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
22660 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
22670 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
22680 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
22690 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
226a0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
226b0 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
226c0 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
226d0 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
226e0 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
226f0 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
22700 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
22710 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
22720 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
22730 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
22740 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
22750 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22760 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
22770 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
22780 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
22790 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
227a0 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
227b0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
227c0 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
227d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
227e0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
227f0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
22800 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
22810 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
22820 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
22830 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
22840 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
22850 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
22860 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
22870 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
22880 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
22890 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
228a0 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
228b0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
228c0 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
228d0 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
228e0 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
228f0 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
22900 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
22910 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
22920 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22930 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22940 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
22950 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
22960 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
22970 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
22980 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
22990 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
229a0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
229b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
229c0 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
229d0 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
229e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
229f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22a00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22a10 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
22a20 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
22a30 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
22a40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22a50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22a60 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
22a70 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
22a80 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22a90 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22aa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22ab0 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
22ac0 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
22ad0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
22ae0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22af0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22b00 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
22b10 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
22b20 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
22b30 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22b40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22b50 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
22b60 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
22b70 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
22b80 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22b90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22ba0 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
22bb0 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
22bc0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
22bd0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22be0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
22bf0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
22c00 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
22c10 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22c20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22c30 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22c40 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
22c50 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
22c60 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
22c70 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22c80 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
22c90 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
22ca0 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
22cb0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22cc0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22cd0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
22ce0 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
22cf0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
22d00 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
22d10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22d20 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
22d30 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
22d40 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22d50 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22d60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22d70 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
22d80 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
22d90 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
22da0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
22db0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22dc0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
22dd0 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
22de0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
22df0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22e00 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22e10 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
22e20 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
22e30 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
22e40 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22e50 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22e60 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
22e70 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
22e80 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
22e90 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22ea0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22eb0 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
22ec0 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
22ed0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22ee0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22ef0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22f00 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
22f10 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
22f20 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
22f30 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
22f40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22f50 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
22f60 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
22f70 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
22f80 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
22f90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22fa0 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
22fb0 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
22fc0 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
22fd0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22fe0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
22ff0 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
23000 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
23010 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
23020 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23030 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
23040 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
23050 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
23060 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
23070 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
23080 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
23090 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
230a0 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
230b0 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
230c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
230d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
230e0 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
230f0 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
23100 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
23110 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
23120 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
23130 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
23140 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
23150 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
23160 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
23170 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
23180 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
23190 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
231a0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
231b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
231c0 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
231d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
231e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
231f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23200 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23210 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
23220 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
23230 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
23240 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
23250 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23260 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
23270 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
23280 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
23290 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
232a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
232b0 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
232c0 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
232d0 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
232e0 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
232f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23300 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
23310 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
23320 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
23330 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
23340 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23350 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
23360 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
23370 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
23380 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23390 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20  E_RECURSIVE     
233a0 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e         33   /* N
233b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
233c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
233d0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
233e0 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
233f0 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
23400 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
23410 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73  lite3.**.** Thes
23420 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
23430 65 70 72 65 63 61 74 65 64 2e 20 55 73 65 20 74  eprecated. Use t
23440 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
23450 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  e_v2()] interfac
23460 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20  e.** instead of 
23470 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64 65 73  the routines des
23480 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  cribed here..**.
23490 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
234a0 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
234b0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
234c0 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
234d0 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
234e0 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
234f0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
23500 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
23510 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
23520 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
23530 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
23540 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
23550 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
23560 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
23570 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
23580 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
23590 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
235a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
235b0 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
235c0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
235d0 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
235e0 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
235f0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
23600 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
23610 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
23620 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
23630 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
23640 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
23650 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
23660 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
23670 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
23680 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
23690 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
236a0 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
236b0 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
236c0 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
236d0 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
236e0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  .)^.**.** The [S
236f0 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
23700 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
23710 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20  time option can 
23720 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74  be used to limit
23730 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  .** the length o
23740 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
23750 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e  er] expansion in
23760 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73   the output of s
23770 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a  qlite3_trace()..
23780 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
23790 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
237a0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
237b0 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
237c0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
237d0 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
237e0 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
237f0 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
23800 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
23810 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
23820 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
23830 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
23840 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
23850 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
23860 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
23870 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
23880 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
23890 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
238a0 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
238b0 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
238c0 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
238d0 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
238e0 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
238f0 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
23900 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
23910 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
23920 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
23930 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
23940 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
23950 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
23960 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
23970 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
23980 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
23990 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
239a0 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
239b0 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
239c0 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
239d0 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
239e0 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
239f0 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
23a00 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
23a10 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
23a20 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
23a30 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
23a40 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
23a50 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
23a60 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
23a70 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  void*);.SQLITE_D
23a80 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a  EPRECATED void *
23a90 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
23aa0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
23ab0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
23ac0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
23ad0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
23ae0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
23af0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61  API3REF: SQL Tra
23b00 63 65 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a  ce Event Codes.*
23b10 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
23b20 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54  TE_TRACE.**.** T
23b30 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69  hese constants i
23b40 64 65 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20  dentify classes 
23b50 6f 66 20 65 76 65 6e 74 73 20 74 68 61 74 20 63  of events that c
23b60 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a  an be monitored.
23b70 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71  ** using the [sq
23b80 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
23b90 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e  ] tracing logic.
23ba0 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
23bb0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
23bc0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20  te3_trace_v2()] 
23bd0 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62  is an OR-ed comb
23be0 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f  ination of one o
23bf0 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65  r more of.** the
23c00 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74   following const
23c10 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72 73  ants.  ^The firs
23c20 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
23c30 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  e trace callback
23c40 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  .** is one of th
23c50 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73  e following cons
23c60 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  tants..**.** New
23c70 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e   tracing constan
23c80 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ts may be added 
23c90 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
23ca0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61  es..**.** ^A tra
23cb0 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 20  ce callback has 
23cc0 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20  four arguments: 
23cd0 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c  xCallback(T,C,P,
23ce0 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72  X)..** ^The T ar
23cf0 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66  gument is one of
23d00 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79 70   the integer typ
23d10 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a  e codes above..*
23d20 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e  * ^The C argumen
23d30 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  t is a copy of t
23d40 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  he context point
23d50 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  er passed in as 
23d60 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72  the.** fourth ar
23d70 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
23d80 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a  e3_trace_v2()]..
23d90 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61  ** The P and X a
23da0 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69  rguments are poi
23db0 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e  nters whose mean
23dc0 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54  ings depend on T
23dd0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
23de0 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  [[SQLITE_TRACE_S
23df0 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TMT]] <dt>SQLITE
23e00 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e  _TRACE_STMT</dt>
23e10 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
23e20 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 61  TE_TRACE_STMT ca
23e30 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
23e40 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72 65  d when a prepare
23e50 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66  d statement.** f
23e60 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e 6e  irst begins runn
23e70 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c 79  ing and possibly
23e80 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73 20   at other times 
23e90 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78  during the.** ex
23ea0 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 70  ecution of the p
23eb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23ec0 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74 68  t, such as at th
23ed0 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68 0a  e start of each.
23ee0 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70 72  ** trigger subpr
23ef0 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 72  ogram. ^The P ar
23f00 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
23f10 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70  ter to the.** [p
23f20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23f30 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75 6d  t]. ^The X argum
23f40 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
23f50 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
23f60 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e 65  ch.** is the une
23f70 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78 74  xpanded SQL text
23f80 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64   of the prepared
23f90 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e   statement or an
23fa0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a   SQL comment .**
23fb0 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
23fc0 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  the invocation o
23fd0 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e 54  f a trigger.  ^T
23fe0 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20  he callback can 
23ff0 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 73  compute.** the s
24000 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77 6f  ame text that wo
24010 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72 65  uld have been re
24020 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c 65  turned by the le
24030 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 72  gacy [sqlite3_tr
24040 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ace()].** interf
24050 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68 65  ace by using the
24060 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e   X argument when
24070 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20 22   X begins with "
24080 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67  --" and invoking
24090 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 70  .** [sqlite3_exp
240a0 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74  anded_sql(P)] ot
240b0 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b  herwise..**.** [
240c0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52  [SQLITE_TRACE_PR
240d0 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  OFILE]] <dt>SQLI
240e0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
240f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e  </dt>.** <dd>^An
24100 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52   SQLITE_TRACE_PR
24110 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70  OFILE callback p
24120 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d  rovides approxim
24130 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a  ately the same.*
24140 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  * information as
24150 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
24160 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  the [sqlite3_pro
24170 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b  file()] callback
24180 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75  ..** ^The P argu
24190 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
241a0 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  r to the [prepar
241b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
241c0 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d  d the.** X argum
241d0 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
241e0 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 77  64-bit integer w
241f0 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74 69  hich is the esti
24200 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20  mated of.** the 
24210 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65  number of nanose
24220 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70 72  cond that the pr
24230 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24240 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a   took to run..**
24250 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52 41   ^The SQLITE_TRA
24260 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62  CE_PROFILE callb
24270 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
24280 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
24290 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a  t finishes..**.*
242a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
242b0 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _ROW]] <dt>SQLIT
242c0 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e  E_TRACE_ROW</dt>
242d0 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
242e0 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 6c  TE_TRACE_ROW cal
242f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
24300 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65 70   whenever a prep
24310 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
24320 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73 69  t generates a si
24330 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75  ngle row of resu
24340 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20  lt.  .** ^The P 
24350 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
24360 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72  inter to the [pr
24370 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24380 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61  ] and the.** X a
24390 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65  rgument is unuse
243a0 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d..**.** [[SQLIT
243b0 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20  E_TRACE_CLOSE]] 
243c0 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
243d0 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  _CLOSE</dt>.** <
243e0 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
243f0 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61  ACE_CLOSE callba
24400 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
24410 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  en a database.**
24420 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
24430 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72  es..** ^The P ar
24440 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
24450 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
24460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
24470 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74   object.** and t
24480 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  he X argument is
24490 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c   unused..** </dl
244a0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
244b0 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 20  ITE_TRACE_STMT  
244c0 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e       0x01.#defin
244d0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  e SQLITE_TRACE_P
244e0 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a 23  ROFILE    0x02.#
244f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
24500 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20 30  ACE_ROW        0
24510 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  x04.#define SQLI
24520 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 20  TE_TRACE_CLOSE  
24530 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20      0x08../*.** 
24540 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72  CAPI3REF: SQL Tr
24550 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48  ace Hook.** METH
24560 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
24570 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
24580 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29  race_v2(D,M,X,P)
24590 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
245a0 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61 6c  ters a trace cal
245b0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
245c0 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61 74  n X against [dat
245d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
245e0 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 65  ] D, using prope
245f0 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e  rty mask M.** an
24600 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65  d context pointe
24610 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58 20  r P.  ^If the X 
24620 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e  callback is.** N
24630 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d 20  ULL or if the M 
24640 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68  mask is zero, th
24650 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64 69  en tracing is di
24660 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  sabled.  The.** 
24670 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  M argument shoul
24680 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73 65  d be the bitwise
24690 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69   OR-ed combinati
246a0 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72  on of.** zero or
246b0 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 52   more [SQLITE_TR
246c0 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a  ACE] constants..
246d0 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c  **.** ^Each call
246e0 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69 74   to either sqlit
246f0 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71  e3_trace() or sq
24700 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
24710 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 28   overrides .** (
24720 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 69  cancels) any pri
24730 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  or calls to sqli
24740 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73  te3_trace() or s
24750 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
24760 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20  )..**.** ^The X 
24770 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
24780 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 79  ked whenever any
24790 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20 69   of the events i
247a0 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a 2a  dentified by .**
247b0 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20   mask M occur.  
247c0 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65 74  ^The integer ret
247d0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 74  urn value from t
247e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63  he callback is c
247f0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f  urrently.** igno
24800 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69 73  red, though this
24810 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66   may change in f
24820 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20  uture releases. 
24830 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70   Callback.** imp
24840 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
24850 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f 20  uld return zero 
24860 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72 65  to ensure future
24870 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
24880 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63  **.** ^A trace c
24890 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
248a0 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72 67  ed with four arg
248b0 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b  uments: callback
248c0 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54  (T,C,P,X)..** ^T
248d0 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73  he T argument is
248e0 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 4c   one of the [SQL
248f0 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f  ITE_TRACE].** co
24900 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 63  nstants to indic
24910 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c 6c  ate why the call
24920 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64  back was invoked
24930 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75  ..** ^The C argu
24940 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f  ment is a copy o
24950 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f  f the context po
24960 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20  inter..** The P 
24970 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20  and X arguments 
24980 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f  are pointers who
24990 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65  se meanings depe
249a0 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54  nd on T..**.** T
249b0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
249c0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
249d0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 72  is intended to r
249e0 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61 63  eplace the legac
249f0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
24a00 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
24a10 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
24a20 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20  rofile()], both 
24a30 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 20  of which.** are 
24a40 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69  deprecated..*/.i
24a50 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  nt sqlite3_trace
24a60 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
24a70 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 73  .  unsigned uMas
24a80 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62  k,.  int(*xCallb
24a90 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f  ack)(unsigned,vo
24aa0 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29  id*,void*,void*)
24ab0 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a 29  ,.  void *pCtx.)
24ac0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24ad0 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
24ae0 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d  s Callbacks.** M
24af0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
24b00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
24b10 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
24b20 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
24b30 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
24b40 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
24b50 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
24b60 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
24b70 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
24b80 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
24b90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
24ba0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
24bb0 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
24bc0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
24bd0 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
24be0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
24bf0 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
24c00 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
24c10 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
24c20 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
24c30 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
24c40 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
24c50 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
24c60 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
24c70 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
24c80 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
24c90 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
24ca0 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
24cb0 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f  r N is the appro
24cc0 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66  ximate number of
24cd0 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
24ce0 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
24cf0 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
24d00 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
24d10 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
24d20 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
24d30 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66  callback X.  ^If
24d40 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
24d50 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f  one then the pro
24d60 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72  gress.** handler
24d70 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a   is disabled..**
24d80 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67  .** ^Only a sing
24d90 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  le progress hand
24da0 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e  ler may be defin
24db0 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70  ed at one time p
24dc0 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  er.** [database 
24dd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74  connection]; set
24de0 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72  ting a new progr
24df0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63  ess handler canc
24e00 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f  els the.** old o
24e10 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61  ne.  ^Setting pa
24e20 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c  rameter X to NUL
24e30 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70  L disables the p
24e40 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
24e50 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73  .** ^The progres
24e60 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73  s handler is als
24e70 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  o disabled by se
24e80 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c  tting N to a val
24e90 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  ue less.** than 
24ea0 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  1..**.** ^If the
24eb0 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
24ec0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
24ed0 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
24ee0 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
24ef0 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
24f00 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
24f10 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
24f20 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
24f30 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
24f40 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
24f50 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
24f60 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
24f70 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
24f80 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
24f90 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
24fa0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24fb0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
24fc0 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
24fd0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
24fe0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
24ff0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
25000 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25010 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
25020 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
25030 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
25040 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
25050 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
25060 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a  aragraph..**.*/.
25070 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
25080 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
25090 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
250a0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
250b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
250c0 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
250d0 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
250e0 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52  ection.** CONSTR
250f0 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a  UCTOR: sqlite3.*
25100 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
25110 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
25120 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
25130 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62  e as specified b
25140 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61  y the .** filena
25150 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68  me argument. ^Th
25160 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
25170 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74  ent is interpret
25180 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a  ed as UTF-8 for.
25190 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
251a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
251b0 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55  en_v2() and as U
251c0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
251d0 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65  ive byte.** orde
251e0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  r for sqlite3_op
251f0 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74  en16(). ^(A [dat
25200 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25210 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61  ] handle is usua
25220 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lly.** returned 
25230 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69  in *ppDb, even i
25240 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
25250 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63  s.  The only exc
25260 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a  eption is that.*
25270 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75  * if SQLite is u
25280 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
25290 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  e memory to hold
252a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
252b0 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c  bject,.** a NULL
252c0 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e   will be written
252d0 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74   into *ppDb inst
252e0 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72  ead of a pointer
252f0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
25300 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e  ].** object.)^ ^
25310 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  (If the database
25320 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f   is opened (and/
25330 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63  or created) succ
25340 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a  essfully, then.*
25350 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  * [SQLITE_OK] is
25360 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65   returned.  Othe
25370 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
25380 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
25390 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71  d.)^ ^The.** [sq
253a0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20  lite3_errmsg()] 
253b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  or [sqlite3_errm
253c0 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  sg16()] routines
253d0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
253e0 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67  obtain.** an Eng
253f0 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65  lish language de
25400 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65  scription of the
25410 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67   error following
25420 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e   a failure of an
25430 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  y.** of the sqli
25440 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69  te3_open() routi
25450 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nes..**.** ^The 
25460 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
25470 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66   will be UTF-8 f
25480 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65  or databases cre
25490 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71  ated using.** sq
254a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
254b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
254c0 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74  ).  ^The default
254d0 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61   encoding for da
254e0 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74  tabases.** creat
254f0 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
25500 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62  _open16() will b
25510 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  e UTF-16 in the 
25520 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
25530 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  r..**.** Whether
25540 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
25550 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
25560 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
25570 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
25580 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
25590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
255a0 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
255b0 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
255c0 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
255d0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
255e0 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
255f0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
25600 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25610 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
25620 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
25630 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
25640 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
25650 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
25660 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
25670 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
25680 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
25690 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
256a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
256b0 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61    ^(The flags pa
256c0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71  rameter to.** sq
256d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
256e0 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a  can take one of.
256f0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
25700 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f   three values, o
25710 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
25720 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
25730 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
25740 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
25750 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20  PEN_FULLMUTEX], 
25760 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
25770 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53  REDCACHE],.** [S
25780 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
25790 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72  TECACHE], and/or
257a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
257b0 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a  I] flags:)^.**.*
257c0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
257d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
257e0 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
257f0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
25800 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
25810 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
25820 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
25830 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
25840 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
25850 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
25860 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
25870 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
25880 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a  EADWRITE]</dt>.*
25890 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
258a0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
258b0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
258c0 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65  ting if possible
258d0 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20  , or reading.** 
258e0 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65  only if the file
258f0 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63   is write protec
25900 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61  ted by the opera
25910 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e  ting system.  In
25920 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20   either.** case 
25930 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73  the database mus
25940 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  t already exist,
25950 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72   otherwise an er
25960 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
25970 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
25980 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
25990 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
259a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
259b0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
259c0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
259d0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
259e0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61  g and writing, a
259f0 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66  nd is created if
25a00 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  .** it does not 
25a10 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54  already exist. T
25a20 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76  his is the behav
25a30 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61  ior that is alwa
25a40 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73  ys used for.** s
25a50 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
25a60 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  d sqlite3_open16
25a70 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  ().</dd>)^.** </
25a80 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  dl>.**.** If the
25a90 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
25aa0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25ab0 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  2() is not one o
25ac0 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61  f the.** combina
25ad0 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
25ae0 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  e optionally com
25af0 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72  bined with other
25b00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
25b10 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49  _READONLY | SQLI
25b20 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a  TE_OPEN_* bits].
25b30 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
25b40 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
25b50 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
25b60 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
25b70 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
25b80 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
25b90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25ba0 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
25bb0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
25bc0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
25bd0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
25be0 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
25bf0 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
25c00 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
25c10 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
25c20 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
25c30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
25c40 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
25c50 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
25c60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25c70 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
25c80 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
25c90 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
25ca0 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
25cb0 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
25cc0 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
25cd0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
25ce0 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
25cf0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
25d00 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
25d10 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
25d20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25d30 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
25d40 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
25d50 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
25d60 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
25d70 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
25d80 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
25d90 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
25da0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
25db0 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
25dc0 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
25dd0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
25de0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
25df0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25e00 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
25e10 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
25e20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
25e30 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
25e40 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
25e50 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
25e60 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25e70 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74  3_open_v2() is t
25e80 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
25e90 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
25ea0 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69  object that defi
25eb0 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  nes the operatin
25ec0 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
25ed0 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  ce that.** the n
25ee0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
25ef0 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  ection should us
25f00 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72  e.  ^If the four
25f10 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
25f20 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
25f30 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75  r then the defau
25f40 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
25f50 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
25f60 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
25f70 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d  ilename is ":mem
25f80 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72  ory:", then a pr
25f90 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
25fa0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
25fb0 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65  ase.** is create
25fc0 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63  d for the connec
25fd0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d  tion.  ^This in-
25fe0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20  memory database 
25ff0 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e  will vanish when
26000 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
26010 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
26020 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76  losed.  Future v
26030 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
26040 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20  e might.** make 
26050 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61  use of additiona
26060 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61  l special filena
26070 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77  mes that begin w
26080 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72  ith the ":" char
26090 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20  acter..** It is 
260a0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
260b0 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
260c0 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c   filename actual
260d0 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69  ly does begin wi
260e0 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72  th.** a ":" char
260f0 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64  acter you should
26100 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65   prefix the file
26110 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68  name with a path
26120 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20  name such as.** 
26130 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d  "./" to avoid am
26140 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  biguity..**.** ^
26150 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
26160 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
26170 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  ng, then a priva
26180 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a  te, temporary.**
26190 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73   on-disk databas
261a0 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65  e will be create
261b0 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74  d.  ^This privat
261c0 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  e database will 
261d0 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  be.** automatica
261e0 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73  lly deleted as s
261f0 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62  oon as the datab
26200 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
26210 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
26220 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  [[URI filenames 
26230 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  in sqlite3_open(
26240 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65  )]] <h3>URI File
26250 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a  names</h3>.**.**
26260 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61   ^If [URI filena
26270 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69  me] interpretati
26280 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61  on is enabled, a
26290 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  nd the filename 
262a0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69  argument.** begi
262b0 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c  ns with "file:",
262c0 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61   then the filena
262d0 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  me is interprete
262e0 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49  d as a URI. ^URI
262f0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74  .** filename int
26300 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
26310 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53  nabled if the [S
26320 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
26330 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69  flag is.** set i
26340 6e 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  n the third argu
26350 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
26360 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
26370 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
26380 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
26390 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
263a0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
263b0 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
263c0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
263d0 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
263e0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
263f0 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
26400 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 55  ime option..** U
26410 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
26420 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
26430 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
26440 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
26450 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
26460 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
26470 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
26480 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
26490 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
264a0 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
264b0 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
264c0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
264d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
264e0 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
264f0 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
26500 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
26510 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
26520 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
26530 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
26540 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
26550 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
26560 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
26570 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
26580 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
26590 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
265a0 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
265b0 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
265c0 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
265d0 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
265e0 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
265f0 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
26600 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
26610 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
26620 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
26630 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
26640 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
26650 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
26660 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
26670 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
26680 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
26690 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
266a0 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
266b0 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
266c0 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
266d0 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
266e0 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
266f0 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
26700 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
26710 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
26720 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
26730 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
26740 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
26750 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
26760 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
26770 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f  ve path. .** ^(O
26780 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
26790 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
267a0 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
267b0 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
267c0 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
267d0 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a  (e.g. "C:").)^.*
267e0 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20  *.** [[core URI 
267f0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
26800 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20  ]].** The query 
26810 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
26820 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70  RI may contain p
26830 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
26840 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a  re interpreted.*
26850 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69  * either by SQLi
26860 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79  te itself, or by
26870 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d   a [VFS | custom
26880 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
26890 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ion]..** SQLite 
268a0 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e  and its built-in
268b0 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72   [VFSes] interpr
268c0 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  et the.** follow
268d0 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65  ing query parame
268e0 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
268f0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
26900 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
26910 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
26920 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
26930 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
26940 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
26950 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
26960 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
26970 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
26980 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
26990 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
269a0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
269b0 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
269c0 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
269d0 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
269e0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
269f0 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
26a00 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
26a10 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
26a20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
26a30 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
26a40 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
26a50 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
26a60 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
26a70 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
26a80 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
26a90 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
26aa0 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
26ab0 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
26ac0 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
26ad0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
26ae0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
26af0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
26b00 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
26b10 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
26b20 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
26b30 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
26b40 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
26b50 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
26b60 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
26b70 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
26b80 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
26b90 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
26ba0 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
26bb0 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
26bc0 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
26bd0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
26be0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
26bf0 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
26c00 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
26c10 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
26c20 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
26c30 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
26c40 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
26c50 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
26c60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26c70 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
26c80 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
26c90 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
26ca0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
26cb0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
26cc0 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
26cd0 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
26ce0 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
26cf0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
26d00 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
26d10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
26d20 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
26d30 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
26d40 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
26d50 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
26d60 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
26d70 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
26d80 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
26d90 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
26da0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
26db0 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
26dc0 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
26dd0 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
26de0 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
26df0 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
26e00 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
26e10 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
26e20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
26e30 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
26e40 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
26e50 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
26e60 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
26e70 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
26e80 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
26e90 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
26ea0 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
26eb0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
26ec0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
26ed0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
26ee0 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
26ef0 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
26f00 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
26f10 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
26f20 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
26f30 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
26f40 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
26f50 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
26f60 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
26f70 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
26f80 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
26f90 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
26fa0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
26fb0 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
26fc0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
26fd0 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
26fe0 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
26ff0 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
27000 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
27010 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
27020 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
27030 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
27040 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
27050 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
27060 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
27070 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
27080 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
27090 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
270a0 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
270b0 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71  any behavior req
270c0 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
270d0 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
270e0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
270f0 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
27100 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
27110 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  g..**.**  <li> <
27120 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65  b>psow</b>: ^The
27130 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20   psow parameter 
27140 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65  indicates whethe
27150 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20  r or not the.** 
27160 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f      [powersafe o
27170 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72  verwrite] proper
27180 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20  ty does or does 
27190 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65  not apply to the
271a0 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20  .**     storage 
271b0 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74  media on which t
271c0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
271d0 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20   resides..**.** 
271e0 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c   <li> <b>nolock<
271f0 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b  /b>: ^The nolock
27200 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
27210 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61  boolean query pa
27220 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77  rameter.**     w
27230 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61  hich if set disa
27240 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e  bles file lockin
27250 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f  g in rollback jo
27260 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68  urnal modes.  Th
27270 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65  is.**     is use
27280 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e  ful for accessin
27290 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20  g a database on 
272a0 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61  a filesystem tha
272b0 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  t does not.**   
272c0 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e    support lockin
272d0 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61  g.  Caution:  Da
272e0 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
272f0 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  n might result i
27300 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20  f two.**     or 
27310 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77  more processes w
27320 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65  rite to the same
27330 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e   database and an
27340 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a  y one of those.*
27350 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20  *     processes 
27360 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a  uses nolock=1..*
27370 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d  *.**  <li> <b>im
27380 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68  mutable</b>: ^Th
27390 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61  e immutable para
273a0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
273b0 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20  an query.**     
273c0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
273d0 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
273e0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
273f0 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20  is stored on.** 
27400 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65      read-only me
27410 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75  dia.  ^When immu
27420 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51  table is set, SQ
27430 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
27440 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74  t the.**     dat
27450 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f  abase file canno
27460 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76  t be changed, ev
27470 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20  en by a process 
27480 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20  with higher.**  
27490 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e     privilege, an
274a0 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73  d so the databas
274b0 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64  e is opened read
274c0 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f  -only and all lo
274d0 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64  cking.**     and
274e0 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f   change detectio
274f0 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  n is disabled.  
27500 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67  Caution: Setting
27510 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a   the immutable.*
27520 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f  *     property o
27530 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
27540 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66  e that does in f
27550 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72  act change can r
27560 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20  esult.**     in 
27570 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20  incorrect query 
27580 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b  results and/or [
27590 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20  SQLITE_CORRUPT] 
275a0 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53  errors..**     S
275b0 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
275c0 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
275d0 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20  ]..**       .** 
275e0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65  </ul>.**.** ^Spe
275f0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
27600 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  wn parameter in 
27610 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  the query compon
27620 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20  ent of a URI is 
27630 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e  not an.** error.
27640 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
27650 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
27660 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64  t understand add
27670 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a  itional query.**
27680 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65   parameters.  Se
27690 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65  e "[query parame
276a0 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61  ters with specia
276b0 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c  l meaning to SQL
276c0 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64  ite]" for.** add
276d0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
276e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  ion..**.** [[URI
276f0 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
27700 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c  es]] <h3>URI fil
27710 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f  ename examples</
27720 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65  h3>.**.** <table
27730 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67   border="1" alig
27740 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64  n=center cellpad
27750 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c  ding=5>.** <tr><
27760 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  th> URI filename
27770 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a  s <th> Results.*
27780 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
27790 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
277a0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
277b0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
277c0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
277d0 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c   directory..** <
277e0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
277f0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c  me/fred/data.db<
27800 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  br>.**          
27810 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65  file:///home/fre
27820 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a  d/data.db <br> .
27830 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
27840 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d  ://localhost/hom
27850 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
27860 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  br> <td> .**    
27870 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64        Open the d
27880 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68  atabase file "/h
27890 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
278a0 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
278b0 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68  ile://darkstar/h
278c0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
278d0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
278e0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61     An error. "da
278f0 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61  rkstar" is not a
27900 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68   recognized auth
27910 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ority..** <tr><t
27920 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73  d style="white-s
27930 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a  pace:nowrap"> .*
27940 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
27950 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25  ///C:/Documents%
27960 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73  20and%20Settings
27970 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61  /fred/Desktop/da
27980 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64  ta.db.**     <td
27990 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20  > Windows only: 
279a0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
279b0 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27  ata.db" on fred'
279c0 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69  s desktop on dri
279d0 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  ve.**          C
279e0 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  :. Note that the
279f0 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e   %20 escaping in
27a00 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73   this example is
27a10 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a   not strictly .*
27a20 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73  *          neces
27a30 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61  sary - space cha
27a40 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75  racters can be u
27a50 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a  sed literally.**
27a60 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49            in URI
27a70 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c   filenames..** <
27a80 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
27a90 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63  a.db?mode=ro&cac
27aa0 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20  he=private <td> 
27ab0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
27ac0 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  n file "data.db"
27ad0 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
27ae0 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65  directory for re
27af0 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a  ad-only access..
27b00 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61  **          Rega
27b10 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
27b20 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d  r or not shared-
27b30 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
27b40 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  abled by.**     
27b50 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73       default, us
27b60 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68  e a private cach
27b70 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  e..** <tr><td> f
27b80 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
27b90 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d  ata.db?vfs=unix-
27ba0 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20  dotfile <td>.** 
27bb0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
27bc0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
27bd0 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
27be0 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
27bf0 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20  ix-dotfile".**  
27c00 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65          that use
27c10 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70  s dot-files in p
27c20 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64  lace of posix ad
27c30 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a  visory locking..
27c40 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
27c50 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65  :data.db?mode=re
27c60 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20  adonly <td> .** 
27c70 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
27c80 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73  r. "readonly" is
27c90 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74   not a valid opt
27ca0 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64  ion for the "mod
27cb0 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  e" parameter..**
27cc0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20   </table>.**.** 
27cd0 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c  ^URI hexadecimal
27ce0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
27cf0 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70  s (%HH) are supp
27d00 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65  orted within the
27d10 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65   path and.** que
27d20 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
27d30 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65   a URI. A hexade
27d40 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
27d50 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f  uence consists o
27d60 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73  f a.** percent s
27d70 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c  ign - "%" - foll
27d80 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20  owed by exactly 
27d90 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20  two hexadecimal 
27da0 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69  digits .** speci
27db0 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76  fying an octet v
27dc0 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68  alue. ^Before th
27dd0 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20  e path or query 
27de0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a  components of a.
27df0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
27e00 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c  are interpreted,
27e10 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65   they are encode
27e20 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e  d using UTF-8 an
27e30 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65  d all .** hexade
27e40 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
27e50 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20  uences replaced 
27e60 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65  by a single byte
27e70 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
27e80 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ** corresponding
27e90 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20   octet. If this 
27ea0 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65  process generate
27eb0 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46  s an invalid UTF
27ec0 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20  -8 encoding,.** 
27ed0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
27ee0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
27ef0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
27f00 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
27f10 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
27f20 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
27f30 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
27f40 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
27f50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
27f60 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
27f70 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
27f80 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
27f90 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
27fa0 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
27fb0 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
27fc0 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
27fd0 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
27fe0 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
27ff0 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
28000 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
28010 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
28020 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
28030 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  2()..**.** <b>No
28040 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75  te to Windows Ru
28050 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e  ntime users:</b>
28060 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20    The temporary 
28070 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62  directory must b
28080 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74  e set.** prior t
28090 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  o calling sqlite
280a0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
280b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
280c0 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f  Otherwise, vario
280d0 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74  us.** features t
280e0 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20  hat require the 
280f0 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79  use of temporary
28100 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e   files may fail.
28110 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
28120 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   [sqlite3_temp_d
28130 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74  irectory].*/.int
28140 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
28150 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
28160 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
28170 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
28180 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
28190 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
281a0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
281b0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
281c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
281d0 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
281e0 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
281f0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
28200 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
28210 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
28220 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
28230 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
28240 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
28250 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
28260 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
28270 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
28280 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
28290 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
282a0 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
282b0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
282c0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
282d0 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
282e0 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
282f0 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
28300 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
28310 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
28320 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
28330 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28340 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
28350 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
28360 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ers.**.** These 
28370 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74  are utility rout
28380 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20  ines, useful to 
28390 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
283a0 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a  ons, that check.
283b0 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
283c0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
283d0 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
283e0 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
283f0 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
28400 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
28410 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
28420 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20  e of that query 
28430 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
28440 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74   If F is the dat
28450 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70  abase filename p
28460 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
28470 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d  to the xOpen() m
28480 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56  ethod of .** a V
28490 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
284a0 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73  n when the flags
284b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
284c0 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72  pen() has one or
284d0 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65   .** more of the
284e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
284f0 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  I] or [SQLITE_OP
28500 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73  EN_MAIN_DB] bits
28510 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73   set and.** P is
28520 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
28530 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
28540 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
28550 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
28560 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65  F,P) returns the
28570 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a   value of the P.
28580 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
28590 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e  it exists or a N
285a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50  ULL pointer if P
285b0 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72   does not appear
285c0 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20   as a .** query 
285d0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20  parameter on F. 
285e0 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79   If P is a query
285f0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a   parameter of F.
28600 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63  ** has no explic
28610 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73  it value, then s
28620 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
28630 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
28640 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
28650 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
28660 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  g..**.** The sql
28670 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
28680 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
28690 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69  assumes that P i
286a0 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70  s a boolean.** p
286b0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
286c0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72  urns true (1) or
286d0 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72   false (0) accor
286e0 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75  ding to the valu
286f0 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20  e.** of P.  The 
28700 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
28710 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
28720 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ne returns true 
28730 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61  (1) if the.** va
28740 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72  lue of query par
28750 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
28760 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22  of "yes", "true"
28770 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79  , or "on" in any
28780 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74  .** case or if t
28790 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
287a0 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  with a non-zero 
287b0 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a  number.  The .**
287c0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
287d0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
287e0 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c  ines returns fal
287f0 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61  se (0) if the va
28800 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20  lue of.** query 
28810 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
28820 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c  ne of "no", "fal
28830 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e  se", or "off" in
28840 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20   any case or.** 
28850 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
28860 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72  ins with a numer
28870 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69  ic zero.  If P i
28880 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a  s not a query.**
28890 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20   parameter on F 
288a0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
288b0 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74  of P is does not
288c0 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68   match any of th
288d0 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e  e.** above, then
288e0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
288f0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
28900 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a  rns (B!=0)..**.*
28910 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
28920 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72  i_int64(F,P,D) r
28930 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20  outine converts 
28940 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
28950 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20  nto a.** 64-bit 
28960 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
28970 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  nd returns that 
28980 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66  integer, or D if
28990 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65   P does not.** e
289a0 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61  xist.  If the va
289b0 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65  lue of P is some
289c0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
289d0 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
289e0 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74  n.** zero is ret
289f0 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  urned..** .** If
28a00 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   F is a NULL poi
28a10 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  nter, then sqlit
28a20 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
28a30 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55  (F,P) returns NU
28a40 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  LL and.** sqlite
28a50 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
28a60 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20  P,B) returns B. 
28a70 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e   If F is not a N
28a80 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a  ULL pointer and.
28a90 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  ** is not a data
28aa0 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61  base file pathna
28ab0 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  me pointer that 
28ac0 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e  SQLite passed in
28ad0 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
28ae0 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  VFS method, then
28af0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
28b00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
28b10 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
28b20 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73  robably.** undes
28b30 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74  irable..*/.const
28b40 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75   char *sqlite3_u
28b50 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
28b60 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
28b70 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
28b80 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c  zParam);.int sql
28b90 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
28ba0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
28bb0 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
28bc0 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
28bd0 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69  ault);.sqlite3_i
28be0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69  nt64 sqlite3_uri
28bf0 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61  _int64(const cha
28c00 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  r*, const char*,
28c10 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
28c20 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
28c30 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
28c40 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d  nd Messages.** M
28c50 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
28c60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
28c70 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33  t recent sqlite3
28c80 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f  _* API call asso
28c90 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20  ciated with .** 
28ca0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
28cb0 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20  tion] D failed, 
28cc0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
28cd0 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65  _errcode(D) inte
28ce0 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
28cf0 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
28d00 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65  sult code] or [e
28d10 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
28d20 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a  ode] for that.**
28d30 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66   API call..** If
28d40 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
28d50 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75   API call was su
28d60 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65  ccessful,.** the
28d70 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
28d80 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
28d90 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
28da0 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  efined..** ^The 
28db0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
28dc0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
28dd0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
28de0 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
28df0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
28e00 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
28e10 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
28e20 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
28e30 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
28e40 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
28e50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
28e60 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
28e70 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
28e80 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
28e90 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
28ea0 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
28eb0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
28ec0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
28ed0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
28ee0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
28ef0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
28f00 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
28f10 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
28f20 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
28f30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
28f40 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
28f50 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
28f60 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
28f70 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
28f80 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
28f90 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
28fa0 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
28fb0 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
28fc0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
28fd0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
28fe0 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
28ff0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29000 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
29010 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
29020 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
29030 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
29040 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
29050 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
29060 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
29070 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
29080 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
29090 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
290a0 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
290b0 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
290c0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
290d0 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
290e0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
290f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
29100 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
29110 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
29120 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
29130 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
29140 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
29150 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
29160 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
29170 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
29180 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
29190 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
291a0 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
291b0 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
291c0 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
291d0 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
291e0 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
291f0 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
29200 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
29210 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
29220 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
29230 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
29240 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
29250 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
29260 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
29270 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
29280 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
29290 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
292a0 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
292b0 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
292c0 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
292d0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
292e0 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
292f0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
29300 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
29310 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
29320 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
29330 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
29340 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
29350 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
29360 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
29370 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
29380 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
29390 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
293a0 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
293b0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
293c0 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
293d0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
293e0 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
293f0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
29400 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
29410 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
29420 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
29430 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
29440 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
29450 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
29460 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
29470 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
29480 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
29490 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  6(sqlite3*);.con
294a0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
294b0 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
294c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
294d0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
294e0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
294f0 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
29500 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
29510 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
29520 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
29530 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
29540 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
29550 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
29560 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20  ent that.** has 
29570 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e  been compiled in
29580 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61  to binary form a
29590 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62  nd is ready to b
295a0 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a  e evaluated..**.
295b0 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68  ** Think of each
295c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
295d0 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d  s a separate com
295e0 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20  puter program.  
295f0 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  The.** original 
29600 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72  SQL text is sour
29610 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70  ce code.  A prep
29620 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
29630 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65  bject .** is the
29640 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74   compiled object
29650 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20   code.  All SQL 
29660 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
29670 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70  d into a.** prep
29680 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62  ared statement b
29690 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20  efore it can be 
296a0 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  run..**.** The l
296b0 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70  ife-cycle of a p
296c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
296d0 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79  t object usually
296e0 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a   goes like this:
296f0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
29700 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70  li> Create the p
29710 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29720 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  t object using [
29730 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
29740 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  v2()]..** <li> B
29750 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70  ind values to [p
29760 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
29770 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
29780 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
29790 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
297a0 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
297b0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
297c0 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
297d0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
297e0 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70  <li> Reset the p
297f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29800 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
29810 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
29820 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
29830 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
29840 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
29850 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
29860 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
29870 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
29880 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
29890 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65   </ol>.*/.typede
298a0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
298b0 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
298c0 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
298d0 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
298e0 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  mits.** METHOD: 
298f0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28  sqlite3.**.** ^(
29900 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
29910 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
29920 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
29930 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
29940 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
29950 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
29960 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
29970 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
29980 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
29990 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
299a0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
299b0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
299c0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
299d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
299e0 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
299f0 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
29a00 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
29a10 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
29a20 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
29a30 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
29a40 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
29a50 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
29a60 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
29a70 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uct.)^.**.** ^If
29a80 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
29a90 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
29aa0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
29ab0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
29ac0 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74  ^(For each limit
29ad0 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45   category SQLITE
29ae0 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f  _LIMIT_<i>NAME</
29af0 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  i> there is a .*
29b00 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
29b10 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
29b20 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
29b30 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70  time by a C prep
29b40 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63  rocessor macro c
29b50 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73  alled.** [limits
29b60 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69   | SQLITE_MAX_<i
29b70 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28  >NAME</i>]..** (
29b80 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
29b90 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
29ba0 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
29bb0 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73  ))^.** ^Attempts
29bc0 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
29bd0 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
29be0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
29bf0 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
29c00 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
29c10 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
29c20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64  d..**.** ^Regard
29c30 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
29c40 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74  or not the limit
29c50 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68   was changed, th
29c60 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  e .** [sqlite3_l
29c70 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  imit()] interfac
29c80 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72  e returns the pr
29c90 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ior value of the
29ca0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63   limit..** ^Henc
29cb0 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63  e, to find the c
29cc0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
29cd0 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20  a limit without 
29ce0 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20  changing it,.** 
29cf0 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68  simply invoke th
29d00 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  is interface wit
29d10 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  h the third para
29d20 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e  meter set to -1.
29d30 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20  .**.** Run-time 
29d40 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
29d50 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
29d60 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
29d70 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
29d80 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
29d90 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
29da0 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
29db0 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
29dc0 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
29dd0 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
29de0 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
29df0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
29e00 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62  ht be a.** web b
29e10 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
29e20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
29e30 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
29e40 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
29e50 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
29e60 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
29e70 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
29e80 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
29e90 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
29ea0 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
29eb0 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
29ec0 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
29ed0 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
29ee0 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
29ef0 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
29f00 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
29f10 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
29f20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
29f30 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
29f40 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
29f50 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
29f60 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
29f70 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
29f80 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
29f90 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
29fa0 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
29fb0 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
29fc0 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
29fd0 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
29fe0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
29ff0 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
2a000 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
2a010 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
2a020 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
2a030 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
2a040 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
2a050 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
2a060 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
2a070 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
2a080 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
2a090 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2a0a0 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
2a0b0 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
2a0c0 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
2a0d0 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
2a0e0 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
2a0f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
2a100 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
2a110 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
2a120 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
2a130 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
2a140 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
2a150 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
2a160 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
2a170 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
2a180 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
2a190 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
2a1a0 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
2a1b0 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
2a1c0 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
2a1d0 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
2a1e0 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
2a1f0 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
2a200 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
2a210 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
2a220 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
2a230 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2a240 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
2a250 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2a260 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
2a270 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
2a280 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
2a290 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
2a2a0 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
2a2b0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a2c0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
2a2d0 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
2a2e0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
2a2f0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
2a300 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
2a310 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
2a320 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
2a330 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2a340 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
2a350 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
2a360 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
2a370 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
2a380 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2a390 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2a3a0 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
2a3b0 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
2a3c0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
2a3d0 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
2a3e0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2a3f0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
2a400 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
2a410 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
2a420 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
2a430 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a440 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
2a450 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
2a460 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
2a470 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
2a480 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
2a490 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
2a4a0 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
2a4b0 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
2a4c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2a4d0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
2a4e0 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
2a4f0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
2a500 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
2a510 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a520 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
2a530 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
2a540 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
2a550 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2a560 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
2a570 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
2a580 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2a590 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
2a5a0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2a5b0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
2a5c0 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
2a5d0 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
2a5e0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
2a5f0 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
2a600 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65  ent.  If [sqlite
2a610 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2a620 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61  or.** the equiva
2a630 6c 65 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c  lent tries to al
2a640 6c 6f 63 61 74 65 20 73 70 61 63 65 20 66 6f 72  locate space for
2a650 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20   more than this 
2a660 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20  many opcodes.** 
2a670 69 6e 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70  in a single prep
2a680 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20  ared statement, 
2a690 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  an SQLITE_NOMEM 
2a6a0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
2a6b0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
2a6c0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  [[SQLITE_LIMIT_F
2a6d0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28  UNCTION_ARG]] ^(
2a6e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a6f0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
2a700 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2a710 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2a720 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
2a730 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
2a740 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a750 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20  IMIT_ATTACHED]] 
2a760 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a770 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
2a780 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2a790 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
2a7a0 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
2a7b0 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
2a7c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
2a7d0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
2a7e0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a  TTERN_LENGTH]].*
2a7f0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
2a800 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
2a810 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
2a820 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a830 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
2a840 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
2a850 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
2a860 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
2a870 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tors.</dd>)^.**.
2a880 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a890 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2a8a0 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  R]].** ^(<dt>SQL
2a8b0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2a8c0 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
2a8d0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a8e0 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
2a8f0 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
2a900 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
2a910 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  ement.)^.**.** [
2a920 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  [SQLITE_LIMIT_TR
2a930 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28  IGGER_DEPTH]] ^(
2a940 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a950 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
2a960 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2a970 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
2a980 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
2a990 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
2a9a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2a9b0 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
2a9c0 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  DS]] ^(<dt>SQLIT
2a9d0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
2a9e0 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  HREADS</dt>.** <
2a9f0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2aa00 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61  umber of auxilia
2aa10 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64  ry worker thread
2aa20 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a  s that a single.
2aa30 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2aa40 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72  tement] may star
2aa50 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  t.</dd>)^.** </d
2aa60 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
2aa70 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2aa80 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
2aa90 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
2aaa0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
2aab0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
2aac0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
2aad0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
2aae0 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
2aaf0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
2ab00 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
2ab10 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
2ab20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
2ab30 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
2ab40 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
2ab50 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
2ab60 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2ab70 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
2ab80 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
2ab90 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2aba0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
2abb0 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
2abc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2abd0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
2abe0 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
2abf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2ac00 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
2ac10 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
2ac20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2ac30 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2ac40 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
2ac50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2ac60 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
2ac70 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
2ac80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ac90 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
2aca0 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31  EADS           1
2acb0 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  1../*.** CAPI3RE
2acc0 46 3a 20 50 72 65 70 61 72 65 20 46 6c 61 67 73  F: Prepare Flags
2acd0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2ace0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
2acf0 72 69 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74  rious flags that
2ad00 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 69   can be passed i
2ad10 6e 74 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67  nto.** "prepFlag
2ad20 73 22 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  s" parameter of 
2ad30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
2ad40 70 61 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a  pare_v3()] and.*
2ad50 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2ad60 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 74 65 72  re16_v3()] inter
2ad70 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  faces..**.** New
2ad80 20 66 6c 61 67 73 20 6d 61 79 20 62 65 20 61 64   flags may be ad
2ad90 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
2ada0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
2adb0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
2adc0 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  [[SQLITE_PREPARE
2add0 5f 50 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28  _PERSISTENT]] ^(
2ade0 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41  <dt>SQLITE_PREPA
2adf0 52 45 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f 64  RE_PERSISTENT</d
2ae00 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51  t>.** <dd>The SQ
2ae10 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2ae20 53 49 53 54 45 4e 54 20 66 6c 61 67 20 69 73 20  SISTENT flag is 
2ae30 61 20 68 69 6e 74 20 74 6f 20 74 68 65 20 71 75  a hint to the qu
2ae40 65 72 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74  ery planner.** t
2ae50 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
2ae60 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2ae70 62 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  be retained for 
2ae80 61 20 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a  a long time and.
2ae90 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 75 73  ** probably reus
2aea0 65 64 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e  ed many times.)^
2aeb0 20 5e 57 69 74 68 6f 75 74 20 74 68 69 73 20 66   ^Without this f
2aec0 6c 61 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  lag, [sqlite3_pr
2aed0 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61  epare_v3()].** a
2aee0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2aef0 61 72 65 31 36 5f 76 33 28 29 5d 20 61 73 73 75  are16_v3()] assu
2af00 6d 65 20 74 68 61 74 20 74 68 65 20 70 72 65 70  me that the prep
2af10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77  ared statement w
2af20 69 6c 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64 20  ill .** be used 
2af30 6a 75 73 74 20 6f 6e 63 65 20 6f 72 20 61 74 20  just once or at 
2af40 6d 6f 73 74 20 61 20 66 65 77 20 74 69 6d 65 73  most a few times
2af50 20 61 6e 64 20 74 68 65 6e 20 64 65 73 74 72 6f   and then destro
2af60 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  yed using.** [sq
2af70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2af80 5d 20 72 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f  ] relatively soo
2af90 6e 2e 20 54 68 65 20 63 75 72 72 65 6e 74 20 69  n. The current i
2afa0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63  mplementation ac
2afb0 74 73 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69  ts.** on this hi
2afc0 6e 74 20 62 79 20 61 76 6f 69 64 69 6e 67 20 74  nt by avoiding t
2afd0 68 65 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61  he use of [looka
2afe0 73 69 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20  side memory] so 
2aff0 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70  as not to.** dep
2b000 6c 65 74 65 20 74 68 65 20 6c 69 6d 69 74 65 64  lete the limited
2b010 20 73 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73   store of lookas
2b020 69 64 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75  ide memory. Futu
2b030 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a  re versions of.*
2b040 2a 20 53 51 4c 69 74 65 20 6d 61 79 20 61 63 74  * SQLite may act
2b050 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 64 69   on this hint di
2b060 66 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f  fferently..** </
2b070 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
2b080 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2b090 52 53 49 53 54 45 4e 54 20 20 20 20 20 20 20 20  RSISTENT        
2b0a0 20 20 20 20 20 20 30 78 30 31 0a 0a 2f 2a 0a 2a        0x01../*.*
2b0b0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
2b0c0 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
2b0d0 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
2b0e0 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
2b0f0 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20  nt compiler}.** 
2b100 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
2b110 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
2b120 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2b130 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
2b140 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2b150 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
2b160 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
2b170 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
2b180 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
2b190 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2b1a0 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65 72  s.  Or, in other
2b1b0 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20 72 6f   words, these ro
2b1c0 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63 6f  utines.** are co
2b1d0 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 74  nstructors for t
2b1e0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2b1f0 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a  tement] object..
2b200 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66 65 72  **.** The prefer
2b210 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f 20 75  red routine to u
2b220 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33 5f 70  se is [sqlite3_p
2b230 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20 20 54  repare_v2()].  T
2b240 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
2b250 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65 72 66  repare()] interf
2b260 61 63 65 20 69 73 20 6c 65 67 61 63 79 20 61 6e  ace is legacy an
2b270 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  d should be avoi
2b280 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ded..** [sqlite3
2b290 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 68  _prepare_v3()] h
2b2a0 61 73 20 61 6e 20 65 78 74 72 61 20 22 70 72 65  as an extra "pre
2b2b0 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20 74  pFlags" option t
2b2c0 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a 20 66  hat is used.** f
2b2d0 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72 70 6f  or special purpo
2b2e0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ses..**.** The u
2b2f0 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20  se of the UTF-8 
2b300 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 70 72  interfaces is pr
2b310 65 66 65 72 72 65 64 2c 20 61 73 20 53 51 4c 69  eferred, as SQLi
2b320 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  te currently.** 
2b330 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69 6e 67  does all parsing
2b340 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20 20 54   using UTF-8.  T
2b350 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66  he UTF-16 interf
2b360 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
2b370 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65 6e  d.** as a conven
2b380 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54 46 2d  ience.  The UTF-
2b390 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f  16 interfaces wo
2b3a0 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69 6e 67  rk by converting
2b3b0 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74 65   the.** input te
2b3c0 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20 74  xt into UTF-8, t
2b3d0 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hen invoking the
2b3e0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 55   corresponding U
2b3f0 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 2e 0a  TF-8 interface..
2b400 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2b410 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
2b420 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
2b430 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
2b440 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
2b450 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
2b460 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2b470 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2b480 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
2b490 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
2b4a0 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
2b4b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2b4c0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
2b4d0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
2b4e0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2b4f0 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
2b500 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
2b510 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
2b520 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
2b530 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
2b540 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
2b550 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73 71 6c  3_prepare(), sql
2b560 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2b570 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2b580 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 0a 2a  3_prepare_v3().*
2b590 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
2b5a0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
2b5b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 2c  te3_prepare16(),
2b5c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b5d0 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  16_v2(),.** and 
2b5e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b5f0 36 5f 76 33 28 29 20 75 73 65 20 55 54 46 2d 31  6_v3() use UTF-1
2b600 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
2b610 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
2b620 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2b630 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
2b640 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
2b650 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2b660 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
2b670 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69  positive, then i
2b680 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  t is the.** numb
2b690 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64  er of bytes read
2b6a0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66   from zSql.  ^If
2b6b0 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20   nByte is zero, 
2b6c0 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64  then no prepared
2b6d0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73  .** statement is
2b6e0 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49   generated..** I
2b6f0 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
2b700 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ws that the supp
2b710 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
2b720 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
2b730 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20  hen.** there is 
2b740 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61  a small performa
2b750 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
2b760 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
2b770 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
2b780 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2b790 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2b7a0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
2b7b0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
2b7c0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
2b7d0 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nator..**.** ^If
2b7e0 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
2b7f0 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
2b800 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
2b810 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
2b820 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
2b830 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
2b840 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
2b850 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
2b860 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
2b870 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
2b880 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
2b890 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
2b8a0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2b8b0 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
2b8c0 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
2b8d0 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
2b8e0 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
2b8f0 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
2b900 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b910 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
2b920 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
2b930 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2b940 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
2b950 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
2b960 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
2b970 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
2b980 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
2b990 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
2b9a0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
2b9b0 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
2b9c0 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
2b9d0 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
2b9e0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
2b9f0 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
2ba00 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
2ba10 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
2ba20 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
2ba30 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
2ba40 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
2ba50 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
2ba60 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2ba70 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
2ba80 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
2ba90 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
2baa0 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
2bab0 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
2bac0 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
2bad0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
2bae0 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
2baf0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2bb00 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2bb10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
2bb20 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c 69 74  pare_v2(), sqlit
2bb30 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 2c  e3_prepare_v3(),
2bb40 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2bb50 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  16_v2(),.** and 
2bb60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2bb70 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61 63 65  6_v3() interface
2bb80 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64 65  s are recommende
2bb90 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
2bba0 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f  ograms..** The o
2bbb0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
2bbc0 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  (sqlite3_prepare
2bbd0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
2bbe0 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a 20 61  repare16()).** a
2bbf0 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
2bc00 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
2bc10 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
2bc20 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
2bc30 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
2bc40 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65  e "vX" interface
2bc50 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
2bc60 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
2bc70 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
2bc80 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2bc90 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
2bca0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
2bcb0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
2bcc0 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
2bcd0 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
2bce0 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
2bcf0 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
2bd00 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
2bd10 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
2bd20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
2bd30 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
2bd40 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
2bd50 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
2bd60 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
2bd70 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
2bd80 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
2bd90 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2bda0 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
2bdb0 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
2bdc0 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
2bdd0 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
2bde0 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73  run it again. As
2bdf0 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45   many as [SQLITE
2be00 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52  _MAX_SCHEMA_RETR
2be10 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69  Y].** retries wi
2be20 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20  ll occur before 
2be30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67  sqlite3_step() g
2be40 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75  ives up and retu
2be50 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  rns an error..**
2be60 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
2be70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
2be80 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
2be90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2bea0 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
2beb0 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
2bec0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
2bed0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2bee0 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
2bef0 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
2bf00 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
2bf10 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
2bf20 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
2bf30 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
2bf40 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
2bf50 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
2bf60 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
2bf70 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
2bf80 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
2bf90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
2bfa0 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
2bfb0 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
2bfc0 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
2bfd0 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
2bfe0 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
2bff0 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
2c000 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
2c010 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
2c020 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
2c030 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
2c040 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2c050 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2c060 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
2c070 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
2c080 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
2c090 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
2c0a0 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
2c0b0 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
2c0c0 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2c0d0 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
2c0e0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
2c0f0 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
2c100 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
2c110 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
2c120 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
2c130 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
2c140 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
2c150 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c160 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
2c170 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
2c180 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
2c190 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
2c1a0 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
2c1b0 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
2c1c0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
2c1d0 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
2c1e0 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
2c1f0 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2c200 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
2c210 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
2c220 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
2c230 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
2c240 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
2c250 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
2c260 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
2c270 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
2c280 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
2c290 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
2c2a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
2c2b0 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
2c2c0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
2c2d0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c   enabled..** </l
2c2e0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 6c  i>.**.** <p>^sql
2c2f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2c300 29 20 64 69 66 66 65 72 73 20 66 72 6f 6d 20 73  ) differs from s
2c310 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c320 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68 61 76 69  2() only in havi
2c330 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74 72 61 20  ng.** the extra 
2c340 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65  prepFlags parame
2c350 74 65 72 2c 20 77 68 69 63 68 20 69 73 20 61 20  ter, which is a 
2c360 62 69 74 20 61 72 72 61 79 20 63 6f 6e 73 69 73  bit array consis
2c370 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20 6f 72 0a  ting of zero or.
2c380 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
2c390 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2c3a0 45 52 53 49 53 54 45 4e 54 7c 53 51 4c 49 54 45  ERSISTENT|SQLITE
2c3b0 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66 6c 61 67  _PREPARE_*] flag
2c3c0 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  s.  ^The.** sqli
2c3d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2c3e0 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
2c3f0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
2c400 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e as.** sqlite3_
2c410 70 72 65 70 61 72 65 5f 76 33 28 29 20 77 69 74  prepare_v3() wit
2c420 68 20 61 20 7a 65 72 6f 20 70 72 65 70 46 6c 61  h a zero prepFla
2c430 67 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  gs parameter..**
2c440 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
2c450 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
2c460 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2c470 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2c480 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2c490 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2c4a0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2c4b0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2c4c0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2c4d0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2c4e0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2c4f0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2c500 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2c510 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2c520 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2c530 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2c540 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2c550 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2c560 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2c570 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2c580 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
2c590 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c5a0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2c5b0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2c5c0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2c5d0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2c5e0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2c5f0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2c600 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2c610 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2c620 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2c630 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2c640 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2c650 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2c660 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2c670 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2c680 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2c690 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2c6a0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2c6b0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2c6c0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2c6d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
2c6e0 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71 6c  repare_v3(.  sql
2c6f0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2c700 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2c710 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2c720 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2c730 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2c740 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2c750 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2c760 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2c770 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2c780 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2c790 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67  ytes. */.  unsig
2c7a0 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67  ned int prepFlag
2c7b0 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f  s, /* Zero or mo
2c7c0 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  re SQLITE_PREPAR
2c7d0 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71  E_ flags */.  sq
2c7e0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2c7f0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2c800 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2c810 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2c820 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2c830 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2c840 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2c850 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2c860 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c870 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2c880 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2c890 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2c8a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2c8b0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2c8c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2c8d0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2c8e0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2c8f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2c900 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2c910 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2c920 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2c930 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2c940 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2c950 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2c960 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2c970 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2c980 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2c990 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2c9a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
2c9b0 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
2c9c0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2c9d0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2c9e0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2c9f0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2ca00 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2ca10 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2ca20 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2ca30 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2ca40 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2ca50 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2ca60 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2ca70 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2ca80 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2ca90 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2caa0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2cab0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2cac0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2cad0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2cae0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2caf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2cb00 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v3(.  sqlite3 *
2cb10 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2cb20 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2cb30 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2cb40 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2cb50 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2cb60 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2cb70 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2cb80 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2cb90 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2cba0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2cbb0 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69   */.  unsigned i
2cbc0 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a  nt prepFlags, /*
2cbd0 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51   Zero or more SQ
2cbe0 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c  LITE_PREPARE_ fl
2cbf0 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  ags */.  sqlite3
2cc00 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2cc10 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2cc20 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2cc30 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2cc40 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2cc50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2cc60 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2cc70 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2cc80 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
2cc90 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
2cca0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2ccb0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2ccc0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  The sqlite3_sql(
2ccd0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2cce0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2ccf0 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  o a copy of the 
2cd00 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78  UTF-8.** SQL tex
2cd10 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
2cd20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cd30 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73  ment] P if P was
2cd40 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 5b  .** created by [
2cd50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2cd60 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
2cd70 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a 2a  prepare_v3()],.*
2cd80 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2cd90 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b  re16_v2()], or [
2cda0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cdb0 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  6_v3()]..** ^The
2cdc0 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2cdd0 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  d_sql(P) interfa
2cde0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2cdf0 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a  nter to a UTF-8.
2ce00 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
2ce10 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78  ning the SQL tex
2ce20 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74  t of prepared st
2ce30 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a  atement P with.*
2ce40 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  * [bound paramet
2ce50 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a  ers] expanded..*
2ce60 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
2ce70 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 65  le, if a prepare
2ce80 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  d statement is c
2ce90 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65  reated using the
2cea0 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45   SQL.** text "SE
2ceb0 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2cec0 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 72  and if parameter
2ced0 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74   $abc is bound t
2cee0 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a  o integer 2345.*
2cef0 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * and parameter 
2cf00 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c  :xyz is unbound,
2cf10 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71   then sqlite3_sq
2cf20 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  l() will return.
2cf30 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
2cf40 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20  string, "SELECT 
2cf50 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73  $abc,:xyz" but s
2cf60 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2cf70 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  sql().** will re
2cf80 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34  turn "SELECT 234
2cf90 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a  5,NULL".)^.**.**
2cfa0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
2cfb0 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74  panded_sql() int
2cfc0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e  erface returns N
2cfd0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
2cfe0 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73  ent memory.** is
2cff0 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f   available to ho
2d000 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f  ld the result, o
2d010 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20  r if the result 
2d020 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65  would exceed the
2d030 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  .** the maximum 
2d040 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65  string length de
2d050 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
2d060 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2d070 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  NGTH]..**.** ^Th
2d080 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
2d090 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
2d0a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
2d0b0 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20  limits the size 
2d0c0 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61  of.** bound para
2d0d0 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73  meter expansions
2d0e0 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
2d0f0 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70  OMIT_TRACE] comp
2d100 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
2d110 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 65  on causes sqlite
2d120 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2d130 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72   to always retur
2d140 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  n NULL..**.** ^T
2d150 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2d160 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71  ed by sqlite3_sq
2d170 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20  l(P) is managed 
2d180 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73  by SQLite and is
2d190 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
2d1a0 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65  y freed when the
2d1b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d1c0 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2d1d0 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67  ..** ^The string
2d1e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2d1f0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2d200 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68  l(P), on the oth
2d210 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f  er hand,.** is o
2d220 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2d230 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
2d240 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65  and must be free
2d250 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
2d260 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e  ion.** by passin
2d270 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
2d280 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  _free()]..*/.con
2d290 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2d2a0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
2d2b0 74 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20  t *pStmt);.char 
2d2c0 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  *sqlite3_expande
2d2d0 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  d_sql(sqlite3_st
2d2e0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2d2f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
2d300 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
2d310 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65   Statement Write
2d320 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a  s The Database.*
2d330 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2d340 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2d350 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2d360 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72  eadonly(X) inter
2d370 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2d380 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a  e (non-zero) if.
2d390 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  ** and only if t
2d3a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2d3b0 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20  tement] X makes 
2d3c0 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65  no direct change
2d3d0 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  s to.** the cont
2d3e0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2d3f0 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  ase file..**.** 
2d400 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69  Note that [appli
2d410 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2d420 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
2d430 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
2d440 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67  les] might chang
2d450 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
2d460 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73  ndirectly as a s
2d470 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a  ide effect.  .**
2d480 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2d490 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
2d4a0 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63  n defines a func
2d4b0 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68  tion "eval()" th
2d4c0 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71  at .** calls [sq
2d4d0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74  lite3_exec()], t
2d4e0 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  hen the followin
2d4f0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  g SQL statement 
2d500 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20  would.** change 
2d510 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2d520 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65  e through side-e
2d530 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ffects:.**.** <b
2d540 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
2d550 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61  **    SELECT eva
2d560 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  l('DELETE FROM t
2d570 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20  1') FROM t2;.** 
2d580 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
2d590 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65  te>.**.** But be
2d5a0 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43  cause the [SELEC
2d5b0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  T] statement doe
2d5c0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2d5d0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
2d5e0 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69  * directly, sqli
2d5f0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2d600 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20  y() would still 
2d610 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a  return true.)^.*
2d620 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f  *.** ^Transactio
2d630 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d  n control statem
2d640 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45  ents such as [BE
2d650 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20  GIN], [COMMIT], 
2d660 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b  [ROLLBACK],.** [
2d670 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20  SAVEPOINT], and 
2d680 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20  [RELEASE] cause 
2d690 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2d6a0 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
2d6b0 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65  n true,.** since
2d6c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   the statements 
2d6d0 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f  themselves do no
2d6e0 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66  t actually modif
2d6f0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  y the database b
2d700 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65  ut.** rather the
2d710 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69  y control the ti
2d720 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68  ming of when oth
2d730 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f  er statements mo
2d740 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74  dify the .** dat
2d750 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54  abase.  ^The [AT
2d760 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43  TACH] and [DETAC
2d770 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c  H] statements al
2d780 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69  so cause.** sqli
2d790 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2d7a0 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
2d7b0 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20  ue since, while 
2d7c0 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73  those statements
2d7d0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63  .** change the c
2d7e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20  onfiguration of 
2d7f0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
2d800 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e  ction, they do n
2d810 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e  ot make .** chan
2d820 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65  ges to the conte
2d830 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
2d840 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b  se files on disk
2d850 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2d860 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2d870 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2d880 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45  rns true for [BE
2d890 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42  GIN] since.** [B
2d8a0 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74  EGIN] merely set
2d8b0 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73  s internal flags
2d8c0 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e  , but the [BEGIN
2d8d0 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45  |BEGIN IMMEDIATE
2d8e0 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c  ] and.** [BEGIN|
2d8f0 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d  BEGIN EXCLUSIVE]
2d900 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75   commands do tou
2d910 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
2d920 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65  and so.** sqlite
2d930 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2d940 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  ) returns false 
2d950 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e  for those comman
2d960 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ds..*/.int sqlit
2d970 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2d980 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2d990 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2d9a0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
2d9b0 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
2d9c0 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
2d9d0 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48  en Reset.** METH
2d9e0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2d9f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2da00 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2da10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2da20 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2da30 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
2da40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2da50 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
2da60 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
2da70 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
2da80 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
2da90 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72  ut has neither r
2daa0 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
2dab0 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53   (returned.** [S
2dac0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d  QLITE_DONE] from
2dad0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2dae0 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20  )]) nor.** been 
2daf0 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c  reset using [sql
2db00 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20  ite3_reset(S)]. 
2db10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2db20 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e  mt_busy(S).** in
2db30 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2db40 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20  false if S is a 
2db50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
2db60 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a  f S is not a .**
2db70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
2db80 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  d is not a point
2db90 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70  er to a valid [p
2dba0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2dbb0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68  t].** object, th
2dbc0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2dbd0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2dbe0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
2dbf0 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rable..**.** Thi
2dc00 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
2dc10 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69  be used in combi
2dc20 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  nation [sqlite3_
2dc30 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20  next_stmt()].** 
2dc40 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72  to locate all pr
2dc50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2dc60 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2dc70 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  h a database .**
2dc80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
2dc90 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20   are in need of 
2dca0 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68  being reset.  Th
2dcb0 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a  is can be used,.
2dcc0 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** for example, 
2dcd0 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f  in diagnostic ro
2dce0 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68  utines to search
2dcf0 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a   for prepared .*
2dd00 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  * statements tha
2dd10 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20  t are holding a 
2dd20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e  transaction open
2dd30 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2dd40 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
2dd50 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2dd60 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
2dd70 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
2dd80 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
2dd90 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
2dda0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2ddb0 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
2ddc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
2ddd0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
2dde0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
2ddf0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
2de00 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
2de10 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
2de20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
2de30 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
2de40 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
2de50 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
2de60 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
2de70 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
2de80 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
2de90 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
2dea0 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
2deb0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2dec0 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
2ded0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
2dee0 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
2def0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
2df00 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
2df10 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
2df20 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
2df30 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
2df40 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
2df50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2df60 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
2df70 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
2df80 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
2df90 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
2dfa0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2dfb0 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
2dfc0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
2dfd0 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
2dfe0 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
2dff0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
2e000 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
2e010 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
2e020 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2e030 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
2e040 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69  3_value_dup()] i
2e050 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
2e060 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63  used to construc
2e070 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74  t a new .** prot
2e080 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e090 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72  lue from an unpr
2e0a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e0b0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
2e0c0 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
2e0d0 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
2e0e0 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
2e0f0 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
2e100 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
2e110 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
2e120 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
2e130 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
2e140 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2e150 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
2e160 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
2e170 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2e180 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2e190 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
2e1a0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
2e1b0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
2e1c0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
2e1d0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
2e1e0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
2e1f0 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
2e200 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
2e210 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
2e220 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
2e230 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
2e240 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
2e250 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
2e260 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
2e270 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
2e280 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
2e290 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
2e2a0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
2e2b0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
2e2c0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2e2d0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
2e2e0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
2e2f0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
2e300 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
2e310 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
2e320 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
2e330 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
2e340 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
2e350 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
2e360 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
2e370 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
2e380 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
2e390 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2e3a0 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
2e3b0 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
2e3c0 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
2e3d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
2e3e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
2e3f0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
2e400 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
2e410 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
2e420 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
2e430 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2e440 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
2e450 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
2e460 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2e470 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
2e480 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2e490 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2e4a0 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
2e4b0 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
2e4c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e4d0 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
2e4e0 65 20 75 73 65 64 20 61 73 20 61 72 67 75 6d 65  e used as argume
2e4f0 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  nts.** to [sqlit
2e500 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2e510 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  )], [sqlite3_bin
2e520 64 5f 76 61 6c 75 65 28 29 5d 2c 20 61 6e 64 0a  d_value()], and.
2e530 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2e540 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a 20 54 68 65  e_dup()]..** The
2e550 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e560 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
2e570 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
2e580 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
2e590 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
2e5a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e5b0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
2e5c0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2e5d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71  sqlite3_value sq
2e5e0 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
2e5f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
2e600 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
2e610 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
2e620 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
2e630 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
2e640 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
2e650 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
2e660 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2e670 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
2e680 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
2e690 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2e6a0 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
2e6b0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
2e6c0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
2e6d0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2e6e0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
2e6f0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e700 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
2e710 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
2e720 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
2e730 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
2e740 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
2e750 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
2e760 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
2e770 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
2e780 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2e790 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
2e7a0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
2e7b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
2e7c0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
2e7d0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
2e7e0 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
2e7f0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
2e800 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
2e810 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2e820 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2e830 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
2e840 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e850 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
2e860 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
2e870 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
2e880 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
2e890 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
2e8a0 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
2e8b0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
2e8c0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
2e8d0 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
2e8e0 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
2e8f0 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
2e900 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2e910 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
2e920 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
2e930 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
2e940 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
2e950 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
2e960 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
2e970 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
2e980 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
2e990 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
2e9a0 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
2e9b0 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
2e9c0 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
2e9d0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
2e9e0 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
2e9f0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
2ea00 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
2ea10 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
2ea20 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
2ea30 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
2ea40 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
2ea50 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
2ea60 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
2ea70 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
2ea80 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e  ic identifier.)^
2ea90 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
2eaa0 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
2eab0 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
2eac0 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
2ead0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
2eae0 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
2eaf0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
2eb00 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
2eb10 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2eb20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
2eb30 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
2eb40 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
2eb50 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2eb60 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
2eb70 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
2eb80 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2eb90 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
2eba0 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
2ebb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ebc0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
2ebd0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
2ebe0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2ebf0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2ec00 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
2ec10 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
2ec20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
2ec30 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
2ec40 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
2ec50 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
2ec60 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
2ec70 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
2ec80 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
2ec90 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
2eca0 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
2ecb0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
2ecc0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
2ecd0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
2ece0 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
2ecf0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
2ed00 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
2ed10 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
2ed20 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2ed30 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2ed40 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
2ed50 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
2ed60 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
2ed70 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
2ed80 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
2ed90 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
2eda0 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
2edb0 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
2edc0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
2edd0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
2ede0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2edf0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
2ee00 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
2ee10 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
2ee20 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
2ee30 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
2ee40 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
2ee50 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
2ee60 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2ee70 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
2ee80 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2ee90 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73  text16().** or s
2eea0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2eeb0 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
2eec0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f  nter then the fo
2eed0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a  urth parameter.*
2eee0 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64  * is ignored and
2eef0 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20   the end result 
2ef00 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73  is the same as s
2ef10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2ef20 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ()..**.** ^(In t
2ef30 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68  hose routines th
2ef40 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68  at have a fourth
2ef50 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76   argument, its v
2ef60 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2ef70 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2ef80 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  n the parameter.
2ef90 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74    To be clear: t
2efa0 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  he value is the.
2efb0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e  ** number of <u>
2efc0 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65  bytes</u> in the
2efd0 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20   value, not the 
2efe0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
2eff0 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74  ters.)^.** ^If t
2f000 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2f010 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2f020 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2f030 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2f040 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  6().** is negati
2f050 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e  ve, then the len
2f060 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e  gth of the strin
2f070 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  g is.** the numb
2f080 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74  er of bytes up t
2f090 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  o the first zero
2f0a0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20   terminator..** 
2f0b0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2f0c0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2f0d0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69  e3_bind_blob() i
2f0e0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2f0f0 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72  .** the behavior
2f100 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2f110 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  * If a non-negat
2f120 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  ive fourth param
2f130 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64  eter is provided
2f140 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2f150 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _text().** or sq
2f160 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2f170 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  6() or sqlite3_b
2f180 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65  ind_text64() the
2f190 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65  n.** that parame
2f1a0 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
2f1b0 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
2f1c0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
2f1d0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
2f1e0 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
2f1f0 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
2f200 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
2f210 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
2f220 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
2f230 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
2f240 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
2f250 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
2f260 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
2f270 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
2f280 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
2f290 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
2f2a0 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
2f2b0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
2f2c0 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
2f2d0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
2f2e0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
2f2f0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2f300 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
2f310 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c  gument to the BL
2f320 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69  OB and string bi
2f330 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  nding interfaces
2f340 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63  .** is a destruc
2f350 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70  tor used to disp
2f360 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2f370 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74  or.** string aft
2f380 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69  er SQLite has fi
2f390 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20  nished with it. 
2f3a0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
2f3b0 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f   is called.** to
2f3c0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2f3d0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65  BLOB or string e
2f3e0 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ven if the call 
2f3f0 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c  to bind API fail
2f400 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  s..** ^If the fi
2f410 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  fth argument is.
2f420 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76  ** the special v
2f430 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41  alue [SQLITE_STA
2f440 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74  TIC], then SQLit
2f450 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  e assumes that t
2f460 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  he.** informatio
2f470 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20  n is in static, 
2f480 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20  unmanaged space 
2f490 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  and does not nee
2f4a0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a  d to be freed..*
2f4b0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2f4c0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
2f4d0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
2f4e0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
2f4f0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
2f500 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2f510 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
2f520 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
2f530 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
2f540 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2f550 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
2f560 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61  .** ^The sixth a
2f570 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2f580 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2f590 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a   must be one of.
2f5a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ** [SQLITE_UTF8]
2f5b0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
2f5c0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
2f5d0 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
2f5e0 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70  TF16LE].** to sp
2f5f0 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69  ecify the encodi
2f600 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69  ng of the text i
2f610 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
2f620 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68  meter.  If.** th
2f630 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2f640 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2f650 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74  _text64() is not
2f660 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61   one of the.** a
2f670 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68  llowed values sh
2f680 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66  own above, or if
2f690 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
2f6a0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a  ng is different.
2f6b0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f  ** from the enco
2f6c0 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62  ding specified b
2f6d0 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61  y the sixth para
2f6e0 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
2f6f0 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75  behavior.** is u
2f700 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2f710 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2f720 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
2f730 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
2f740 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
2f750 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
2f760 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
2f770 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
2f780 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
2f790 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
2f7a0 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
2f7b0 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
2f7c0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
2f7d0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
2f7e0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
2f7f0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
2f800 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2f810 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
2f820 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
2f830 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
2f840 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
2f850 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
2f860 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
2f870 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
2f880 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
2f890 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
2f8a0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
2f8b0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
2f8c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f8d0 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49  bind_pointer(S,I
2f8e0 2c 50 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65 20  ,P,T,D) routine 
2f8f0 63 61 75 73 65 73 20 74 68 65 20 49 2d 74 68 20  causes the I-th 
2f900 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20  parameter in.** 
2f910 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f920 65 6e 74 5d 20 53 20 74 6f 20 68 61 76 65 20 61  ent] S to have a
2f930 6e 20 53 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e  n SQL value of N
2f940 55 4c 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f  ULL, but to also
2f950 20 62 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   be.** associate
2f960 64 20 77 69 74 68 20 74 68 65 20 70 6f 69 6e 74  d with the point
2f970 65 72 20 50 20 6f 66 20 74 79 70 65 20 54 2e 20  er P of type T. 
2f980 20 5e 44 20 69 73 20 65 69 74 68 65 72 20 61 20   ^D is either a 
2f990 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 0a  NULL pointer or.
2f9a0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
2f9b0 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  a destructor fun
2f9c0 63 74 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53 51  ction for P. ^SQ
2f9d0 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
2f9e0 20 74 68 65 0a 2a 2a 20 64 65 73 74 72 75 63 74   the.** destruct
2f9f0 6f 72 20 44 20 77 69 74 68 20 61 20 73 69 6e 67  or D with a sing
2fa00 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 50  le argument of P
2fa10 20 77 68 65 6e 20 69 74 20 69 73 20 66 69 6e 69   when it is fini
2fa20 73 68 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50 2e  shed using.** P.
2fa30 20 20 54 68 65 20 54 20 70 61 72 61 6d 65 74 65    The T paramete
2fa40 72 20 73 68 6f 75 6c 64 20 62 65 20 61 20 73 74  r should be a st
2fa50 61 74 69 63 20 73 74 72 69 6e 67 2c 20 70 72 65  atic string, pre
2fa60 66 65 72 61 62 6c 79 20 61 20 73 74 72 69 6e 67  ferably a string
2fa70 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68 65  .** literal. The
2fa80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f   sqlite3_bind_po
2fa90 69 6e 74 65 72 28 29 20 72 6f 75 74 69 6e 65 20  inter() routine 
2faa0 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  is part of the.*
2fab0 2a 20 5b 70 6f 69 6e 74 65 72 20 70 61 73 73 69  * [pointer passi
2fac0 6e 67 20 69 6e 74 65 72 66 61 63 65 5d 20 61 64  ng interface] ad
2fad0 64 65 64 20 66 6f 72 20 53 51 4c 69 74 65 20 33  ded for SQLite 3
2fae0 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  .20.0..**.** ^If
2faf0 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
2fb00 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2fb10 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2fb20 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
2fb30 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
2fb40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fb50 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
2fb60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fb70 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
2fb80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2fb90 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
2fba0 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
2fbb0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
2fbc0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
2fbd0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
2fbe0 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
2fbf0 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
2fc00 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
2fc10 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
2fc20 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2fc30 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
2fc40 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
2fc50 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
2fc60 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2fc70 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
2fc80 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
2fc90 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
2fca0 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
2fcb0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
2fcc0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
2fcd0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
2fce0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
2fcf0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
2fd00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
2fd10 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2fd20 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
2fd30 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
2fd40 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
2fd50 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
2fd60 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54  g..** ^[SQLITE_T
2fd70 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20  OOBIG] might be 
2fd80 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2fd90 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67  size of a string
2fda0 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65   or BLOB.** exce
2fdb0 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73  eds limits impos
2fdc0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
2fdd0 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
2fde0 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a  MIT_LENGTH]) or.
2fdf0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c  ** [SQLITE_MAX_L
2fe00 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c  ENGTH]..** ^[SQL
2fe10 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
2fe20 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
2fe30 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
2fe40 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2fe50 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
2fe60 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
2fe70 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
2fe80 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2fe90 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2fea0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2feb0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2fec0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2fed0 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
2fee0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2fef0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2ff00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2ff10 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
2ff20 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2ff30 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
2ff40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2ff50 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2ff60 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  _blob64(sqlite3_
2ff70 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2ff80 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33  t void*, sqlite3
2ff90 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20  _uint64,.       
2ffa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ffb0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2ffc0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2ffd0 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
2ffe0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
2fff0 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
30000 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
30010 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
30020 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
30030 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
30040 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30050 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
30060 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30070 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
30080 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
30090 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
300a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
300b0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
300c0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
300d0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
300e0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
300f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30100 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
30110 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
30120 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
30130 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69  bind_text64(sqli
30140 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
30150 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
30160 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
30170 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30180 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
30190 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63  id*), unsigned c
301a0 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69  har encoding);.i
301b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
301c0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
301d0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
301e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
301f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
30200 64 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65  d_pointer(sqlite
30210 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f  3_stmt*, int, vo
30220 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  id*, const char*
30230 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
30240 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
30250 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
30260 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
30270 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69  int n);.int sqli
30280 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
30290 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
302a0 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
302b0 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20  uint64);../*.** 
302c0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
302d0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
302e0 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  rs.** METHOD: sq
302f0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
30300 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
30310 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
30320 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
30330 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
30340 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
30350 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
30360 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
30370 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
30380 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
30390 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
303a0 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
303b0 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
303c0 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
303d0 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
303e0 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
303f0 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
30400 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
30410 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
30420 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
30430 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
30440 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
30450 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
30460 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
30470 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
30480 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
30490 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
304a0 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
304b0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
304c0 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
304d0 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
304e0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
304f0 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
30500 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
30510 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
30520 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
30530 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
30540 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
30550 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
30560 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30570 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
30580 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
30590 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
305a0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
305b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
305c0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
305d0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
305e0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
305f0 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
30600 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  r.** METHOD: sql
30610 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
30620 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
30630 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
30640 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
30650 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
30660 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
30670 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
30680 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
30690 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
306a0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
306b0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
306c0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
306d0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
306e0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
306f0 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
30700 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
30710 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
30720 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
30730 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
30740 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
30750 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
30760 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
30770 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
30780 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
30790 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
307a0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
307b0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
307c0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
307d0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
307e0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
307f0 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
30800 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
30810 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
30820 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
30830 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
30840 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
30850 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
30860 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
30870 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
30880 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
30890 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
308a0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
308b0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
308c0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
308d0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
308e0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
308f0 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
30900 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
30910 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
30920 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
30930 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
30940 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
30950 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
30960 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
30970 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
30980 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a  pare16_v3()]..**
30990 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
309a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
309b0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
309c0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
309d0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
309e0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
309f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30a00 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
30a10 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
30a20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30a30 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
30a40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
30a50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30a60 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
30a70 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
30a80 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f  en Name.** METHO
30a90 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30aa0 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
30ab0 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
30ac0 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
30ad0 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
30ae0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
30af0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
30b00 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
30b10 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
30b20 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
30b30 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
30b40 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
30b50 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
30b60 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
30b70 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
30b80 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
30b90 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
30ba0 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
30bb0 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
30bc0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
30bd0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
30be0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
30bf0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
30c00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
30c10 31 36 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  16_v2()] or.** [
30c20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
30c30 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v3()]..**.** S
30c40 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
30c50 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
30c60 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
30c70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
30c80 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
30c90 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
30ca0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30cb0 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  _name()]..*/.int
30cc0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
30cd0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
30ce0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
30cf0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
30d00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30d10 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
30d20 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
30d30 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed Statement.** 
30d40 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
30d50 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  stmt.**.** ^Cont
30d60 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
30d70 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
30d80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30d90 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
30da0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
30db0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
30dc0 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
30dd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
30de0 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
30df0 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
30e00 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
30e10 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  rs to NULL..*/.i
30e20 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
30e30 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
30e40 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
30e50 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
30e60 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
30e70 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20  A Result Set.** 
30e80 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
30e90 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
30ea0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
30eb0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
30ec0 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
30ed0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
30ee0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30ef0 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75  t]. ^If this rou
30f00 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20  tine returns 0, 
30f10 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a  that means the .
30f20 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
30f30 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20  tement] returns 
30f40 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  no data (for exa
30f50 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
30f60 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20  )..** ^However, 
30f70 6a 75 73 74 20 62 65 63 61 75 73 65 20 74 68 69  just because thi
30f80 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
30f90 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d  s a positive num
30fa0 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ber does not.** 
30fb0 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72  mean that one or
30fc0 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61   more rows of da
30fd0 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72  ta will be retur
30fe0 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20  ned.  ^A SELECT 
30ff0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c  statement.** wil
31000 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20 61 20  l always have a 
31010 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65 33  positive sqlite3
31020 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20  _column_count() 
31030 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  but depending on
31040 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c   the.** WHERE cl
31050 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
31060 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63   and the table c
31070 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74  ontent, it might
31080 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e   return no rows.
31090 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
310a0 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
310b0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
310c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
310d0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
310e0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
310f0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
31100 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
31110 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
31120 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
31130 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
31140 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
31150 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
31160 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
31170 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
31180 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
31190 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
311a0 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
311b0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
311c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
311d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
311e0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
311f0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
31200 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
31210 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
31220 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
31230 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
31240 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
31250 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
31260 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
31270 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
31280 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
31290 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
312a0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
312b0 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
312c0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
312d0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
312e0 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
312f0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
31300 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
31310 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
31320 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
31330 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
31340 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
31350 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
31360 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
31370 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
31380 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
31390 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
313a0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
313b0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
313c0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
313d0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
313e0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
313f0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
31400 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
31410 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
31420 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
31430 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
31440 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
31450 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
31460 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
31470 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
31480 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
31490 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
314a0 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
314b0 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
314c0 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
314d0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
314e0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
314f0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
31500 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
31510 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
31520 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
31530 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
31540 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
31550 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
31560 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
31570 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
31580 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
31590 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
315a0 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
315b0 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
315c0 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
315d0 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
315e0 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
315f0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
31600 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
31610 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
31620 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
31630 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31640 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
31650 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31660 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
31670 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
31680 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
31690 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
316a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
316b0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
316c0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
316d0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
316e0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
316f0 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
31700 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
31710 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
31720 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
31730 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
31740 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
31750 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
31760 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
31770 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
31780 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
31790 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
317a0 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
317b0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
317c0 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
317d0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
317e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
317f0 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
31800 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
31810 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
31820 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
31830 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
31840 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
31850 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
31860 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
31870 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
31880 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31890 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
318a0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
318b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
318c0 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
318d0 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
318e0 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
318f0 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
31900 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
31910 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
31920 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
31930 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
31940 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
31950 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
31960 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
31970 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
31980 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
31990 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
319a0 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
319b0 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
319c0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
319d0 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
319e0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
319f0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
31a00 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
31a10 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
31a20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
31a30 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
31a40 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
31a50 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
31a60 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
31a70 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
31a80 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
31a90 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
31aa0 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
31ab0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
31ac0 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
31ad0 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
31ae0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
31af0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
31b00 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
31b10 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
31b20 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
31b30 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
31b40 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
31b50 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
31b60 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
31b70 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
31b80 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
31b90 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
31ba0 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
31bb0 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
31bc0 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
31bd0 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
31be0 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
31bf0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
31c00 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
31c10 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
31c20 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
31c30 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
31c40 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
31c50 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
31c60 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
31c70 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
31c80 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
31c90 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
31ca0 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
31cb0 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
31cc0 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
31cd0 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
31ce0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
31cf0 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
31d00 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
31d10 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
31d20 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
31d30 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
31d40 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
31d50 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
31d60 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
31d70 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
31d80 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
31d90 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
31da0 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
31db0 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
31dc0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
31dd0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
31de0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
31df0 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
31e00 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
31e10 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
31e20 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
31e30 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
31e40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
31e50 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
31e60 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
31e70 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
31e80 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
31e90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
31ea0 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
31eb0 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
31ec0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
31ed0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
31ee0 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
31ef0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
31f00 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
31f10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
31f20 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
31f30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
31f40 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
31f50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
31f60 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
31f70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
31f80 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
31f90 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
31fa0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31fb0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
31fc0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
31fd0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
31fe0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
31ff0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
32000 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
32010 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
32020 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
32030 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
32040 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
32050 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32060 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
32070 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
32080 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  esult.** METHOD:
32090 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
320a0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
320b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
320c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
320d0 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
320e0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
320f0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
32100 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
32110 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
32120 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
32130 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
32140 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
32150 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
32160 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
32170 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
32180 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
32190 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
321a0 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
321b0 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
321c0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
321d0 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
321e0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
321f0 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
32200 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
32210 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
32220 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
32230 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
32240 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
32250 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
32260 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
32270 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
32280 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
32290 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
322a0 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
322b0 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
322c0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
322d0 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
322e0 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
322f0 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
32300 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
32310 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
32320 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
32330 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
32340 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
32350 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
32360 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
32370 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
32380 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
32390 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
323a0 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
323b0 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
323c0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
323d0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
323e0 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
323f0 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
32400 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
32410 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
32420 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
32430 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
32440 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
32450 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
32460 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
32470 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
32480 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
32490 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
324a0 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
324b0 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
324c0 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
324d0 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
324e0 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
324f0 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  lues..*/.const c
32500 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
32510 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
32520 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
32530 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
32540 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
32550 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
32560 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
32570 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
32580 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
32590 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
325a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
325b0 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
325c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
325d0 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
325e0 65 64 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a  ed using any of.
325f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
32600 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
32610 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
32620 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
32630 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20  are16_v2()],.** 
32640 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
32650 61 72 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f  are16_v3()] or o
32660 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
32670 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
32680 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
32690 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
326a0 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
326b0 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
326c0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
326d0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
326e0 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
326f0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
32700 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
32710 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
32720 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
32730 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
32740 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
32750 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
32760 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
32770 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 58 22  g the newer "vX"
32780 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b   interfaces.** [
32790 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
327a0 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v3()], [sqlite3_
327b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
327c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
327d0 36 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  6_v3()],.** [sql
327e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
327f0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
32800 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
32810 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
32820 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
32830 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
32840 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
32850 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58  f the.** new "vX
32860 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
32870 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
32880 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
32890 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
328a0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
328b0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
328c0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
328d0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
328e0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
328f0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
32900 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
32910 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
32920 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
32930 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
32940 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
32950 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
32960 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
32970 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
32980 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
32990 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
329a0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
329b0 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
329c0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
329d0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
329e0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
329f0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
32a00 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
32a10 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
32a20 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
32a30 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
32a40 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
32a50 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
32a60 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
32a70 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
32a80 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
32a90 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
32aa0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
32ab0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
32ac0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
32ad0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
32ae0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
32af0 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
32b00 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
32b10 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
32b20 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
32b30 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
32b40 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
32b50 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
32b60 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
32b70 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
32b80 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
32b90 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
32ba0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
32bb0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
32bc0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
32bd0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
32be0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
32bf0 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
32c00 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
32c10 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
32c20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
32c30 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
32c40 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
32c50 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
32c60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
32c70 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
32c80 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
32c90 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
32ca0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
32cb0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
32cc0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
32cd0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
32ce0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
32cf0 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
32d00 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
32d10 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
32d20 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
32d30 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
32d40 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
32d50 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
32d60 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
32d70 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
32d80 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
32d90 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
32da0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
32db0 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
32dc0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
32dd0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
32de0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
32df0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
32e00 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
32e10 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
32e20 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
32e30 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
32e40 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
32e50 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
32e60 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
32e70 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
32e80 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
32e90 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
32ea0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
32eb0 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
32ec0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
32ed0 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
32ee0 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
32ef0 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
32f00 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
32f10 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
32f20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32f30 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
32f40 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
32f50 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
32f60 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
32f70 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
32f80 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
32f90 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
32fa0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
32fb0 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
32fc0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
32fd0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
32fe0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
32ff0 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
33000 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33010 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
33020 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
33030 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
33040 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
33050 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
33060 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
33070 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
33080 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
33090 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
330a0 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
330b0 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
330c0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
330d0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
330e0 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
330f0 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
33100 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
33110 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
33120 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
33130 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
33140 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
33150 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
33160 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
33170 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
33180 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
33190 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
331a0 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
331b0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
331c0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
331d0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
331e0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
331f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
33200 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
33210 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
33220 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
33230 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
33240 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
33250 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
33260 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
33270 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
33280 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
33290 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33   [version 3.6.23
332a0 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36  .1] ([dateof:3.6
332b0 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74  .23.1],.** sqlit
332c0 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
332d0 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
332e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
332f0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
33300 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
33310 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
33320 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
33330 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
33340 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
33350 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
33360 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
33370 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
33380 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
33390 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
333a0 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
333b0 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
333c0 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
333d0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
333e0 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
333f0 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
33400 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
33410 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
33420 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
33430 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
33440 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
33450 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
33460 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
33470 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
33480 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
33490 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
334a0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
334b0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
334c0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
334d0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
334e0 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
334f0 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
33500 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
33510 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
33520 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
33530 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
33540 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
33550 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
33560 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
33570 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
33580 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
33590 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
335a0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
335b0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
335c0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
335d0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
335e0 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
335f0 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
33600 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
33610 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
33620 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
33630 72 65 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v3()] or [sql
33640 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
33650 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
33660 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
33670 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
33680 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e  epare16_v3()] in
33690 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
336a0 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
336b0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
336c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
336d0 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
336e0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
336f0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
33700 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
33710 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
33720 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
33730 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
33740 20 74 68 65 20 22 76 58 22 20 69 6e 74 65 72 66   the "vX" interf
33750 61 63 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e  aces is recommen
33760 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ded..*/.int sqli
33770 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
33780 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
33790 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
337a0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
337b0 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d   result set.** M
337c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
337d0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
337e0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
337f0 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  t(P) interface r
33800 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
33810 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
33820 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72  the.** current r
33830 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ow of the result
33840 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
33850 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
33860 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20  ** ^If prepared 
33870 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73  statement P does
33880 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74   not have result
33890 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72  s ready to retur
338a0 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20  n.** (via calls 
338b0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
338c0 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c  column_int | sql
338d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d  ite3_column_*()]
338e0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
338f0 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  s) then sqlite3_
33900 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65  data_count(P) re
33910 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65  turns 0..** ^The
33920 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
33930 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61  unt(P) routine a
33940 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66  lso returns 0 if
33950 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   P is a NULL poi
33960 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nter..** ^The sq
33970 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
33980 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  (P) routine retu
33990 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65  rns 0 if the pre
339a0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a  vious call to.**
339b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
339c0 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  P) returned [SQL
339d0 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65  ITE_DONE].  ^The
339e0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
339f0 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72  unt(P).** will r
33a00 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69  eturn non-zero i
33a10 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  f previous call 
33a20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
33a30 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ](P) returned.**
33a40 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65   [SQLITE_ROW], e
33a50 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73  xcept in the cas
33a60 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41  e of the [PRAGMA
33a70 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63   incremental_vac
33a80 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74  uum].** where it
33a90 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
33aa0 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20  zero since each 
33ab0 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c  step of that mul
33ac0 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d  ti-step.** pragm
33ad0 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75  a returns 0 colu
33ae0 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a  mns of data..**.
33af0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
33b00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
33b10 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
33b20 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
33b30 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
33b40 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
33b50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
33b60 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
33b70 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
33b80 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
33b90 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
33ba0 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
33bb0 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
33bc0 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
33bd0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
33be0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
33bf0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
33c00 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
33c10 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
33c20 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
33c30 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
33c40 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
33c50 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
33c60 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
33c70 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
33c80 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
33c90 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
33ca0 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
33cb0 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
33cc0 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
33cd0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
33ce0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
33cf0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
33d00 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
33d10 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
33d20 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
33d30 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
33d40 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
33d50 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
33d60 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
33d70 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
33d80 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
33d90 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
33da0 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
33db0 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
33dc0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
33dd0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
33de0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
33df0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
33e00 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
33e10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
33e20 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
33e30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
33e40 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
33e50 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
33e60 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
33e70 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
33e80 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
33e90 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20  s functions}.** 
33ea0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
33eb0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75  stmt.**.** <b>Su
33ec0 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62  mmary:</b>.** <b
33ed0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65  lockquote><table
33ee0 20 62 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70 61   border=0 cellpa
33ef0 64 64 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63  dding=0 cellspac
33f00 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=0>.** <tr><t
33f10 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
33f20 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e  umn_blob</b><td>
33f30 26 72 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72  &rarr;<td>BLOB r
33f40 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
33f50 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
33f60 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64  mn_double</b><td
33f70 3e 26 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20  >&rarr;<td>REAL 
33f80 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
33f90 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
33fa0 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26  umn_int</b><td>&
33fb0 72 61 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20  rarr;<td>32-bit 
33fc0 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a  INTEGER result.*
33fd0 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
33fe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
33ff0 34 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  4</b><td>&rarr;<
34000 74 64 3e 36 34 2d 62 69 74 20 49 4e 54 45 47 45  td>64-bit INTEGE
34010 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e  R result.** <tr>
34020 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
34030 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74  olumn_text</b><t
34040 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d  d>&rarr;<td>UTF-
34050 38 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a  8 TEXT result.**
34060 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
34070 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
34080 36 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  6</b><td>&rarr;<
34090 74 64 3e 55 54 46 2d 31 36 20 54 45 58 54 20 72  td>UTF-16 TEXT r
340a0 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
340b0 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
340c0 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e  mn_value</b><td>
340d0 26 72 61 72 72 3b 3c 74 64 3e 54 68 65 20 72 65  &rarr;<td>The re
340e0 73 75 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b  sult as an .** [
340f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e  sqlite3_value|un
34100 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
34110 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
34120 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73  .** <tr><td>&nbs
34130 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e  p;<td>&nbsp;<td>
34140 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74  &nbsp;.** <tr><t
34150 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
34160 75 6d 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64  umn_bytes</b><td
34170 3e 26 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20  >&rarr;<td>Size 
34180 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20  of a BLOB.** or 
34190 61 20 55 54 46 2d 38 20 54 45 58 54 20 72 65 73  a UTF-8 TEXT res
341a0 75 6c 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20  ult in bytes.** 
341b0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
341c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
341d0 36 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62  6&nbsp;&nbsp;</b
341e0 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26  >.** <td>&rarr;&
341f0 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53  nbsp;&nbsp;<td>S
34200 69 7a 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a  ize of UTF-16.**
34210 20 54 45 58 54 20 69 6e 20 62 79 74 65 73 0a 2a   TEXT in bytes.*
34220 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
34230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
34240 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
34250 64 3e 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74  d>Default.** dat
34260 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73  atype of the res
34270 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c  ult.** </table><
34280 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
34290 2a 2a 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f  ** <b>Details:</
342a0 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  b>.**.** ^These 
342b0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
342c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
342d0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
342e0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
342f0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
34300 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
34310 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
34320 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
34330 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
34340 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
34350 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
34360 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
34370 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
34380 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
34390 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
343a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
343b0 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
343c0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
343d0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
343e0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
343f0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
34400 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
34410 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
34420 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
34430 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
34440 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
34450 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
34460 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
34470 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
34480 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
34490 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
344a0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
344b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
344c0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
344d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
344e0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
344f0 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
34500 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
34510 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
34520 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
34530 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
34540 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
34550 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
34560 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
34570 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
34580 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
34590 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
345a0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
345b0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
345c0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
345d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
345e0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
345f0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
34600 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
34610 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
34620 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
34630 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
34640 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
34650 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
34660 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
34670 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
34680 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
34690 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
346a0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
346b0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
346c0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
346d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
346e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
346f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
34700 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
34710 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
34720 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
34730 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
34740 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
34750 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
34760 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
34770 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
34780 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
34790 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
347a0 20 73 69 78 20 69 6e 74 65 72 66 61 63 65 73 20   six interfaces 
347b0 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c  (_blob, _double,
347c0 20 5f 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f   _int, _int64, _
347d0 74 65 78 74 2c 20 61 6e 64 20 5f 74 65 78 74 31  text, and _text1
347e0 36 29 0a 2a 2a 20 65 61 63 68 20 72 65 74 75 72  6).** each retur
347f0 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61  n the value of a
34800 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
34810 6e 20 61 20 73 70 65 63 69 66 69 63 20 64 61 74  n a specific dat
34820 61 20 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a  a format.  If.**
34830 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
34840 6d 6e 20 69 73 20 6e 6f 74 20 69 6e 69 74 69 61  mn is not initia
34850 6c 6c 79 20 69 6e 20 74 68 65 20 72 65 71 75 65  lly in the reque
34860 73 74 65 64 20 66 6f 72 6d 61 74 20 28 66 6f 72  sted format (for
34870 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20   example,.** if 
34880 74 68 65 20 71 75 65 72 79 20 72 65 74 75 72 6e  the query return
34890 73 20 61 6e 20 69 6e 74 65 67 65 72 20 62 75 74  s an integer but
348a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
348b0 75 6d 6e 5f 74 65 78 74 28 29 20 69 6e 74 65 72  umn_text() inter
348c0 66 61 63 65 0a 2a 2a 20 69 73 20 75 73 65 64 20  face.** is used 
348d0 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20 76  to extract the v
348e0 61 6c 75 65 29 20 74 68 65 6e 20 61 6e 20 61 75  alue) then an au
348f0 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e  tomatic type con
34900 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
34910 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rmed..**.** ^The
34920 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34930 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
34940 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
34950 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
34960 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
34970 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
34980 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
34990 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
349a0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
349b0 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
349c0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
349d0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
349e0 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
349f0 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
34a00 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
34a10 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74  ULL]..** The ret
34a20 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 73 71 6c  urn value of sql
34a30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
34a40 28 29 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  () can be used t
34a50 6f 20 64 65 63 69 64 65 20 77 68 69 63 68 0a 2a  o decide which.*
34a60 2a 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 73  * of the first s
34a70 69 78 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f  ix interface sho
34a80 75 6c 64 20 62 65 20 75 73 65 64 20 74 6f 20 65  uld be used to e
34a90 78 74 72 61 63 74 20 74 68 65 20 63 6f 6c 75 6d  xtract the colum
34aa0 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20  n value..** The 
34ab0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
34ac0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
34ad0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
34ae0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
34af0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 20 74 79  .** automatic ty
34b00 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  pe conversions h
34b10 61 76 65 20 6f 63 63 75 72 72 65 64 20 66 6f 72  ave occurred for
34b20 20 74 68 65 20 76 61 6c 75 65 20 69 6e 20 71 75   the value in qu
34b30 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74  estion.  .** Aft
34b40 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
34b50 73 69 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c 74  sion, the result
34b60 20 6f 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   of calling sqli
34b70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
34b80 29 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  ).** is undefine
34b90 64 2c 20 74 68 6f 75 67 68 20 68 61 72 6d 6c 65  d, though harmle
34ba0 73 73 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ss.  Future.** v
34bb0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
34bc0 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
34bd0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
34be0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
34bf0 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
34c00 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
34c10 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  n..**.** If the 
34c20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
34c30 20 6f 72 20 61 20 54 45 58 54 20 73 74 72 69 6e   or a TEXT strin
34c40 67 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  g, then the sqli
34c50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34c60 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
34c70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
34c80 29 20 69 6e 74 65 72 66 61 63 65 73 20 63 61 6e  ) interfaces can
34c90 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 74 65   be used to dete
34ca0 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a  rmine the size.*
34cb0 2a 20 6f 66 20 74 68 61 74 20 42 4c 4f 42 20 6f  * of that BLOB o
34cc0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  r string..**.** 
34cd0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
34ce0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
34cf0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
34d00 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
34d10 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
34d20 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
34d30 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
34d40 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
34d50 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
34d60 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
34d70 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
34d80 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
34d90 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
34da0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
34db0 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
34dc0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
34dd0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
34de0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
34df0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
34e00 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
34e10 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
34e20 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
34e30 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
34e40 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
34e50 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
34e60 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
34e70 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
34e80 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
34e90 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
34ea0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
34eb0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
34ec0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
34ed0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
34ee0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
34ef0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
34f00 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
34f10 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
34f20 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
34f30 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
34f40 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
34f50 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
34f60 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
34f70 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
34f80 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
34f90 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
34fa0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
34fb0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
34fc0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
34fd0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
34fe0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
34ff0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
35000 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
35010 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
35020 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
35030 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
35040 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
35050 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
35060 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
35070 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
35080 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
35090 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
350a0 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
350b0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
350c0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
350d0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
350e0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
350f0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
35100 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
35110 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
35120 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
35130 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
35140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35150 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
35160 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
35170 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
35180 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
35190 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
351a0 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
351b0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
351c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
351d0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
351e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
351f0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
35200 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
35210 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
35220 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
35230 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
35240 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
35250 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
35260 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
35270 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
35280 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
35290 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
352a0 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
352b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
352c0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
352d0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
352e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
352f0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
35300 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
35310 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
35320 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62  * <b>Warning:</b
35330 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  > ^The object re
35340 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
35350 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
35360 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
35370 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
35380 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
35390 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61   In a multithrea
353a0 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c  ded environment,
353b0 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  .** an unprotect
353c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
353d0 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79   object may only
353e0 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20   be used safely 
353f0 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
35400 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
35410 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
35420 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
35430 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
35440 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
35450 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
35460 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
35470 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
35480 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
35490 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
354a0 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
354b0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
354c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
354d0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
354e0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
354f0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
35500 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
35510 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f  e behavior is no
35520 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a  t threadsafe..**
35530 20 48 65 6e 63 65 2c 20 74 68 65 20 73 71 6c 69   Hence, the sqli
35540 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
35550 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
35560 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79  is normally only
35570 20 75 73 65 66 75 6c 20 77 69 74 68 69 6e 20 74   useful within t
35580 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
35590 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63  n of .** [applic
355a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
355b0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20  L functions] or 
355c0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
355d0 2c 20 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20  , not within.** 
355e0 74 6f 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63  top-level applic
355f0 61 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a  ation code..**.*
35600 2a 20 54 68 65 20 74 68 65 73 65 20 72 6f 75 74  * The these rout
35610 69 6e 65 73 20 6d 61 79 20 61 74 74 65 6d 70 74  ines may attempt
35620 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
35630 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65 20  datatype of the 
35640 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20  result..** ^For 
35650 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
35660 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
35670 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
35680 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
35690 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
356a0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
356b0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
356c0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
356d0 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
356e0 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
356f0 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
35700 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
35710 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
35720 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
35730 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
35740 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
35750 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
35760 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
35770 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
35780 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
35790 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
357a0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
357b0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
357c0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
357d0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
357e0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
357f0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
35800 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
35810 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
35820 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
35830 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
35840 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
35850 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
35860 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
35870 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
35880 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
35890 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
358a0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
358b0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
358c0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
358d0 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c  om integer to fl
358e0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
358f0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
35900 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
35910 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
35920 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  the integer.** <
35930 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
35940 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
35950 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54  <td> Same as INT
35960 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74  EGER->TEXT.** <t
35970 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
35980 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
35990 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
359a0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
359b0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
359c0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
359d0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
359e0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
359f0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
35a00 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
35a10 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42  <td> [CAST] to B
35a20 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  LOB.** <tr><td> 
35a30 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
35a40 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
35a50 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
35a60 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
35a70 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
35a80 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
35a90 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74  o REAL.** <tr><t
35aa0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
35ab0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
35ac0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
35ad0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
35ae0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
35af0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
35b00 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
35b10 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
35b20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
35b30 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
35b40 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
35b50 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
35b60 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
35b70 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
35b80 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
35b90 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
35ba0 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  e>)^.**.** Note 
35bb0 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
35bc0 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
35bd0 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
35be0 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
35bf0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
35c00 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
35c10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35c20 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
35c30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35c40 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
35c50 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
35c60 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
35c70 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
35c80 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
35c90 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
35ca0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
35cb0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
35cc0 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
35cd0 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
35ce0 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
35cf0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
35d00 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
35d10 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
35d20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
35d30 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
35d40 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
35d50 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
35d60 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
35d70 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
35d80 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
35d90 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
35da0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35db0 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
35dc0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
35dd0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
35de0 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
35df0 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
35e00 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
35e10 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
35e20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
35e30 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
35e40 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
35e50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35e60 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
35e70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35e80 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
35e90 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
35ea0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
35eb0 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
35ec0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
35ed0 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
35ee0 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
35ef0 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
35f00 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
35f10 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
35f20 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
35f30 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
35f40 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
35f50 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
35f60 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
35f70 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
35f80 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65  ointer reference
35f90 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  s will have been
35fa0 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
35fb0 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
35fc0 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
35fd0 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
35fe0 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
35ff0 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
36000 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
36010 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
36020 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
36030 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
36040 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
36050 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63  The safest polic
36060 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
36070 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
36080 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
36090 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
360a0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
360b0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
360c0 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
360d0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
360e0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
360f0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
36100 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
36110 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
36120 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
36130 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
36140 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
36150 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
36160 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
36170 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
36180 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
36190 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
361a0 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
361b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
361c0 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
361d0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
361e0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
361f0 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
36200 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
36210 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
36220 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
36230 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
36240 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36250 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
36260 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
36270 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
36280 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
36290 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
362a0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
362b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
362c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
362d0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
362e0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
362f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
36300 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
36310 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
36320 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36330 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
36340 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
36350 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
36360 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
36370 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
36380 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
36390 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
363a0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
363b0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
363c0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
363d0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
363e0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
363f0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
36400 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
36410 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
36420 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
36430 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
36440 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
36450 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
36460 20 6e 6f 74 20 70 61 73 73 20 74 68 65 20 70 6f   not pass the po
36470 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
36480 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
36490 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
364a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
364b0 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
364c0 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
364d0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
364e0 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
364f0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
36500 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
36510 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
36520 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
36530 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
36540 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
36550 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
36560 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
36570 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
36580 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
36590 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
365a0 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
365b0 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
365c0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
365d0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
365e0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
365f0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
36600 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
36610 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
36620 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
36630 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36640 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
36650 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
36660 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36670 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
36680 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71  e3_column_int(sq
36690 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
366a0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
366b0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
366c0 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
366d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
366e0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  ol);.const unsig
366f0 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
36700 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
36710 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
36720 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f   iCol);.const vo
36730 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
36740 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
36750 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
36760 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  l);.sqlite3_valu
36770 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
36780 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
36790 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
367a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
367b0 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
367c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
367d0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
367e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
367f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36800 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
36810 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
36820 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
36830 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
36840 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
36850 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
36860 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
36870 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20  .** DESTRUCTOR: 
36880 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
36890 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
368a0 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
368b0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
368c0 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
368d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
368e0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
368f0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
36900 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
36910 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e  nt encountered n
36920 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69  o errors.** or i
36930 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
36940 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76  is never been ev
36950 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71  aluated, then sq
36960 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
36970 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49   returns.** SQLI
36980 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20  TE_OK.  ^If the 
36990 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
369a0 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d  uation of statem
369b0 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68  ent S failed, th
369c0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  en.** sqlite3_fi
369d0 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e  nalize(S) return
369e0 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  s the appropriat
369f0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
36a00 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65  r.** [extended e
36a10 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
36a20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
36a30 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69  inalize(S) routi
36a40 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
36a50 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
36a60 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65  ring.** the life
36a70 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61   cycle of [prepa
36a80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
36a90 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74  :.** before stat
36aa0 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20  ement S is ever 
36ab0 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72  evaluated, after
36ac0 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
36ad0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
36ae0 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61  3_reset()], or a
36af0 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a  fter any call.**
36b00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
36b10 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20  p()] regardless 
36b20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
36b30 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
36b40 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  has.** completed
36b50 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a   execution..**.*
36b60 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  * ^Invoking sqli
36b70 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f  te3_finalize() o
36b80 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
36b90 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
36ba0 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  o-op..**.** The 
36bb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
36bc0 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20   finalize every 
36bd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36be0 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  ent] in order to
36bf0 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72   avoid.** resour
36c00 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73  ce leaks.  It is
36c10 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f   a grievous erro
36c20 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
36c30 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20  ation to try to 
36c40 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65  use.** a prepare
36c50 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  d statement afte
36c60 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
36c70 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73  nalized.  Any us
36c80 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a  e of a prepared.
36c90 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ** statement aft
36ca0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
36cb0 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73  inalized can res
36cc0 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
36cd0 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61   and.** undesira
36ce0 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63  ble behavior suc
36cf0 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61  h as segfaults a
36d00 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69  nd heap corrupti
36d10 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  on..*/.int sqlit
36d20 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
36d30 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
36d40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36d50 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
36d60 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
36d70 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ject.** METHOD: 
36d80 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
36d90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
36da0 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
36db0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
36dc0 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
36dd0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
36de0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
36df0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
36e00 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
36e10 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
36e20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
36e30 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
36e40 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
36e50 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
36e60 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
36e70 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
36e80 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
36e90 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
36ea0 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
36eb0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
36ec0 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
36ed0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
36ee0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
36ef0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
36f00 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
36f10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
36f20 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
36f30 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
36f40 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
36f50 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
36f60 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
36f70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
36f80 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
36f90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36fa0 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
36fb0 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
36fc0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
36fd0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
36fe0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
36ff0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
37000 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
37010 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
37020 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
37030 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
37040 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
37050 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
37060 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
37070 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
37080 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
37090 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
370a0 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
370b0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
370c0 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
370d0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
370e0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
370f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
37100 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
37110 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
37120 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
37130 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
37140 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
37150 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
37160 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
37170 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
37180 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
37190 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
371a0 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
371b0 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
371c0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
371d0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
371e0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
371f0 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
37200 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
37210 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
37220 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
37230 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
37240 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
37250 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ions}.** METHOD:
37260 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
37270 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
37280 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
37290 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
372a0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
372b0 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
372c0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
372d0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
372e0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
372f0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
37300 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
37310 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
37320 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
37330 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
37340 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
37350 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
37360 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
37370 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
37380 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
37390 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
373a0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
373b0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
373c0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
373d0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
373e0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
373f0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
37400 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
37410 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
37420 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
37430 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
37440 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37450 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
37460 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
37470 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
37480 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
37490 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
374a0 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
374b0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
374c0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
374d0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
374e0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
374f0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
37500 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37510 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
37520 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
37530 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
37540 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
37550 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
37560 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
37570 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
37580 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
37590 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
375a0 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
375b0 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
375c0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
375d0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
375e0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
375f0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
37600 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
37610 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
37620 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
37630 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
37640 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
37650 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
37660 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
37670 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
37680 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
37690 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
376a0 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
376b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
376c0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
376d0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
376e0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
376f0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
37700 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
37710 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
37720 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
37730 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
37740 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
37750 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
37760 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
37770 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
37780 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
37790 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
377a0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
377b0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
377c0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
377d0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
377e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
377f0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
37800 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
37810 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
37820 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
37830 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
37840 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
37850 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
37860 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
37870 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
37880 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
37890 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
378a0 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
378b0 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70  ameters.  The ap
378c0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
378d0 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65   set this parame
378e0 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ter to.** [SQLIT
378f0 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68  E_UTF16LE] if th
37900 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
37910 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
37920 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  s .** [sqlite3_v
37930 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d  alue_text16le()]
37940 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
37950 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
37960 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  ] if the.** impl
37970 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
37980 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  es [sqlite3_valu
37990 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e  e_text16be()] on
379a0 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a   an input, or.**
379b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
379c0 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  if [sqlite3_valu
379d0 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75  e_text16()] is u
379e0 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  sed, or [SQLITE_
379f0 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69  UTF8].** otherwi
37a00 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53  se.  ^The same S
37a10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  QL function may 
37a20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
37a30 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69  ltiple times usi
37a40 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20  ng.** different 
37a50 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
37a60 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64  ncodings, with d
37a70 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65  ifferent impleme
37a80 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20  ntations for.** 
37a90 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  each encoding..*
37aa0 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
37ab0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
37ac0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
37ad0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
37ae0 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
37af0 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
37b00 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
37b10 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
37b20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
37b30 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  on..**.** ^The f
37b40 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
37b50 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62  may optionally b
37b60 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c  e ORed with [SQL
37b70 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
37b80 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  C].** to signal 
37b90 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f  that the functio
37ba0 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  n will always re
37bb0 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65  turn the same re
37bc0 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68  sult given.** th
37bd0 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69  e same inputs wi
37be0 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51  thin a single SQ
37bf0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f  L statement.  Mo
37c00 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  st SQL functions
37c10 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e   are.** determin
37c20 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c  istic.  The buil
37c30 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20  t-in [random()] 
37c40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
37c50 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a  an example of a.
37c60 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ** function that
37c70 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e   is not determin
37c80 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69  istic.  The SQLi
37c90 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  te query planner
37ca0 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70   is able to.** p
37cb0 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61  erform additiona
37cc0 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  l optimizations 
37cd0 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  on deterministic
37ce0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75   functions, so u
37cf0 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51  se.** of the [SQ
37d00 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
37d10 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f  IC] flag is reco
37d20 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f  mmended where po
37d30 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ssible..**.** ^(
37d40 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
37d50 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
37d60 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
37d70 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
37d80 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
37d90 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
37da0 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
37db0 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
37dc0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
37dd0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
37de0 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
37df0 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
37e00 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
37e10 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
37e20 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
37e30 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
37e40 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
37e50 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
37e60 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
37e70 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
37e80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
37e90 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
37ea0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
37eb0 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
37ec0 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
37ed0 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
37ee0 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
37ef0 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
37f00 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
37f10 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
37f20 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
37f30 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
37f40 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
37f50 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
37f60 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
37f70 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
37f80 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
37f90 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
37fa0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
37fb0 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
37fc0 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
37fd0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
37fe0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
37ff0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
38000 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
38010 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
38020 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
38030 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
38040 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
38050 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
38060 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
38070 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
38080 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
38090 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
380a0 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
380b0 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
380c0 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
380d0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
380e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
380f0 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
38100 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
38110 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
38120 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
38130 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
38140 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
38150 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
38160 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
38170 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
38180 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
38190 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
381a0 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
381b0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
381c0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
381d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
381e0 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
381f0 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
38200 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
38210 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
38220 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
38230 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
38240 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
38250 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
38260 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
38270 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
38280 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
38290 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
382a0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
382b0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
382c0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
382d0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
382e0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
382f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
38300 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
38310 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
38320 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
38330 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
38340 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
38350 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
38360 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
38370 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
38380 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
38390 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
383a0 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
383b0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
383c0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
383d0 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
383e0 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
383f0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
38400 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
38410 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
38420 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
38430 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
38440 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
38450 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
38460 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
38470 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
38480 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
38490 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
384a0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
384b0 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
384c0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
384d0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
384e0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
384f0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
38500 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
38510 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
38520 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
38530 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
38540 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
38550 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
38560 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
38570 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
38580 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
38590 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
385a0 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
385b0 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
385c0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
385d0 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
385e0 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
385f0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
38600 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
38610 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
38620 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
38630 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
38640 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
38650 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
38660 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
38670 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
38680 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
38690 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
386a0 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
386b0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
386c0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
386d0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
386e0 20 20 76 6f 69 64 20 28 2a 78