System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact a71d5c6d72fe828515183b943bc5b9a7a51e1acd:


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 33 2e 32 31 2e 30 22 0a 23 64 65      "3.21.0".#de
1210: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
1220: 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 32 31 30  ION_NUMBER 30210
1230: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
1240: 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20  E_SOURCE_ID     
1250: 20 22 32 30 31 37 2d 31 30 2d 32 34 20 31 38 3a   "2017-10-24 18:
1260: 35 35 3a 34 39 20 31 61 35 38 34 65 34 39 39 39  55:49 1a584e4999
1270: 30 36 62 35 63 38 37 65 63 37 64 34 33 64 34 61  06b5c87ec7d43d4a
1280: 62 63 65 36 34 31 66 64 66 30 31 37 63 34 32 31  bce641fdf017c421
1290: 32 35 62 30 38 33 31 30 39 62 63 37 37 63 34 64  25b083109bc77c4d
12a0: 65 34 38 38 32 37 22 0a 0a 2f 2a 0a 2a 2a 20 43  e48827"../*.** C
12b0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
12c0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
12d0: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
12e0: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
12f0: 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73  ersion sqlite3_s
1300: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
1310: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
1320: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
1330: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
1340: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1350: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1360: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1370: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1380: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1390: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
13a0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
13b0: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
13c0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
13d0: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
13e0: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
13f0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
1400: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
1410: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
1420: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
1430: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
1440: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1450: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1460: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1470: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1480: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1490: 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61 74  thus ensure that
14a0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14b0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
14c0: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
14d0: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
14e0: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
14f0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1500: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
1510: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1520: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
1530: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
1540: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 6e  .** assert( strn
1550: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1560: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1570: 55 52 43 45 5f 49 44 2c 38 30 29 3d 3d 30 20 29  URCE_ID,80)==0 )
1580: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1590: 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76  cmp(sqlite3_libv
15a0: 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f  ersion(),SQLITE_
15b0: 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a  VERSION)==0 );.*
15c0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
15d0: 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
15e0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
15f0: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1600: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  tant contains th
1610: 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54  e text of [SQLIT
1620: 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61  E_VERSION].** ma
1630: 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  cro.  ^The sqlit
1640: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20  e3_libversion() 
1650: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1660: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1670: 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69  e.** to the sqli
1680: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
1690: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20  ring constant.  
16a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
16b0: 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63  ersion().** func
16c0: 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64  tion is provided
16d0: 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73   for use in DLLs
16e0: 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73   since DLL users
16f0: 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20   usually do not 
1700: 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61  have.** direct a
1710: 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20  ccess to string 
1720: 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e  constants within
1730: 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a   the DLL.  ^The.
1740: 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  ** sqlite3_libve
1750: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66  rsion_number() f
1760: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1770: 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c  an integer equal
1780: 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56   to.** [SQLITE_V
1790: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20  ERSION_NUMBER]. 
17a0: 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
17b0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
17c0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
17d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
17e0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
17f0: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1800: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
1810: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
1820: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
1830: 6f 72 20 6d 61 63 72 6f 2e 20 20 45 78 63 65 70  or macro.  Excep
1840: 74 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 62  t if SQLite is b
1850: 75 69 6c 74 0a 2a 2a 20 75 73 69 6e 67 20 61 6e  uilt.** using an
1860: 20 65 64 69 74 65 64 20 63 6f 70 79 20 6f 66 20   edited copy of 
1870: 5b 74 68 65 20 61 6d 61 6c 67 61 6d 61 74 69 6f  [the amalgamatio
1880: 6e 5d 2c 20 74 68 65 6e 20 74 68 65 20 6c 61 73  n], then the las
1890: 74 20 66 6f 75 72 20 63 68 61 72 61 63 74 65 72  t four character
18a0: 73 0a 2a 2a 20 6f 66 20 74 68 65 20 68 61 73 68  s.** of the hash
18b0: 20 6d 69 67 68 74 20 62 65 20 64 69 66 66 65 72   might be differ
18c0: 65 6e 74 20 66 72 6f 6d 20 5b 53 51 4c 49 54 45  ent from [SQLITE
18d0: 5f 53 4f 55 52 43 45 5f 49 44 5d 2e 29 5e 0a 2a  _SOURCE_ID].)^.*
18e0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
18f0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
1900: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
1910: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
1920: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1930: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
1940: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
1950: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49  on[];.SQLITE_API
1960: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
1970: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1980: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
1990: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
19a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76  lite3_sourceid(v
19b0: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
19c0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62   int sqlite3_lib
19d0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76  version_number(v
19e0: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
19f0: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
1a00: 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74  Library Compilat
1a10: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67  ion Options Diag
1a20: 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54  nostics.**.** ^T
1a30: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  he sqlite3_compi
1a40: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20  leoption_used() 
1a50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1a60: 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69   0 or 1 .** indi
1a70: 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 74  cating whether t
1a80: 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 74  he specified opt
1a90: 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20  ion was defined 
1aa0: 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  at .** compile t
1ab0: 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ime.  ^The SQLIT
1ac0: 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 65  E_ prefix may be
1ad0: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
1ae0: 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d  e .** option nam
1af0: 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69  e passed to sqli
1b00: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a  n_used().  .**.*
1b20: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
1b30: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b40: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f  () function allo
1b50: 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20  ws iterating.** 
1b60: 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66  over the list of
1b70: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65   options that we
1b80: 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f  re defined at co
1b90: 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a  mpile time by.**
1ba0: 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e   returning the N
1bb0: 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  -th compile time
1bc0: 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20   option string. 
1bd0: 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66   ^If N is out of
1be0: 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74   range,.** sqlit
1bf0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c00: 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 61  _get() returns a
1c10: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1c20: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a  ^The SQLITE_ .**
1c30: 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74   prefix is omitt
1c40: 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69  ed from any stri
1c50: 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
1c60: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1c70: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e  ileoption_get().
1c80: 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20  .**.** ^Support 
1c90: 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74  for the diagnost
1ca0: 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c  ic functions sql
1cb0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1cc0: 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64  on_used().** and
1cd0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ce0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79  option_get() may
1cf0: 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73   be omitted by s
1d00: 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a  pecifying the .*
1d10: 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  * [SQLITE_OMIT_C
1d20: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d30: 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f  GS] option at co
1d40: 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  mpile time..**.*
1d50: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20  * See also: SQL 
1d60: 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74  functions [sqlit
1d70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1d80: 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
1d90: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
1da0: 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20  tion_get()] and 
1db0: 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74  the [compile_opt
1dc0: 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f  ions pragma]..*/
1dd0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
1de0: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
1df0: 4f 4e 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f  ON_DIAGS.SQLITE_
1e00: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1e10: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1e20: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1e30: 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45  OptName);.SQLITE
1e40: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
1e50: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
1e60: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
1e70: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
1e80: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
1e90: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
1ea0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
1eb0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
1ec0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1ed0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
1ee0: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
1ef0: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
1f00: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
1f10: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f  with mutexing co
1f20: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1f30: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1f40: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1f50: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1f60: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1f70: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1f80: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1f90: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1fa0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1fb0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1fc0: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1fd0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1fe0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1ff0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
2000: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
2010: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
2020: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
2030: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
2040: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
2050: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
2060: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
2070: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
2080: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
2090: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
20a0: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
20b0: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
20c0: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
20d0: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
20e0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
20f0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
2100: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
2110: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
2120: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
2130: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
2140: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
2150: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
2160: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
2170: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
2180: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
2190: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
21a0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
21b0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
21c0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
21d0: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
21e0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
21f0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
2200: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
2210: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
2220: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
2230: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
2240: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
2250: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
2260: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
2270: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
2280: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2290: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
22a0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
22b0: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
22c0: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
22d0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
22e0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
22f0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2300: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
2310: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
2320: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
2330: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2340: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2350: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2360: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2370: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2380: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2390: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
23a0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
23b0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
23c0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
23d0: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
23e0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
23f0: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
2400: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
2410: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
2420: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2430: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2440: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2450: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2460: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2470: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2480: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2490: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
24a0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
24b0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
24c0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
24d0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
24e0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
24f0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
2500: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
2510: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
2520: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
2530: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2540: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2550: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2560: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2570: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2580: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2590: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
25a0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
25b0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
25c0: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
25d0: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
25e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
25f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2600: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2610: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2620: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
2630: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2640: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2650: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2660: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2670: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2680: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2690: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
26a0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
26b0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
26c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
26d0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
26e0: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
26f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2700: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2710: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2720: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2730: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
2740: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2750: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
2760: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
2770: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
2780: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
2790: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
27a0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
27b0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
27c0: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
27d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
27e0: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
27f0: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2800: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2810: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2820: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2830: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2840: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2850: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
2860: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
2870: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
2880: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2890: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
28a0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
28b0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
28c0: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
28d0: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
28e0: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
28f0: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2900: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2910: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2920: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2930: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2940: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2950: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
2960: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
2970: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
2980: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
2990: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
29a0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
29b0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
29c0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
29d0: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
29e0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
29f0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2a00: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2a10: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2a20: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2a30: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2a40: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2a50: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
2a60: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
2a70: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
2a80: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
2a90: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
2aa0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
2ab0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2ac0: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2ad0: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2ae0: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2af0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2b00: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66  e_int64;.# ifdef
2b30: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54   SQLITE_UINT64_T
2b40: 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66 20  YPE.    typedef 
2b50: 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59  SQLITE_UINT64_TY
2b60: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2b70: 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74  ;.# else  .    t
2b80: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2b90: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2ba0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
2bb0: 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64  .# endif.#elif d
2bc0: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2bd0: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2be0: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2bf0: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2c00: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2c10: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2c30: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2c40: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2c50: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2c60: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2c70: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2c80: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2c90: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2ca0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2cb0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2cc0: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2cd0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2ce0: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2cf0: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2d00: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2d10: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2d20: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2d30: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2d40: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2d50: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2d60: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2d70: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2d80: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2d90: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2da0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2db0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2dc0: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45  Connection.** DE
2dd0: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2de0: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
2df0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2e00: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2e10: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2e20: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2e30: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2e40: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2e50: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2e60: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2e70: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2e80: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2e90: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ea0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2eb0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2ec0: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2ed0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2ee0: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2ef0: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2f00: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f10: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2f20: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2f30: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2f40: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2f50: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2f60: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2f70: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2f80: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2f90: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2fa0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2fb0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2fc0: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2fd0: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2fe0: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2ff0: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
3000: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
3010: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
3020: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
3030: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
3040: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
3050: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
3060: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
3070: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
3080: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
3090: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
30a0: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
30b0: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
30c0: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
30d0: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
30e0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
30f0: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
3100: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
3110: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
3120: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
3130: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
3140: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
3150: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
3160: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
3170: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
3180: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
3190: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
31a0: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
31b0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
31c0: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
31d0: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
31e0: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
31f0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
3200: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
3210: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
3220: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
3230: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
3240: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
3250: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
3260: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3270: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
3280: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
3290: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
32a0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
32b0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
32c0: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
32d0: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
32e0: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
32f0: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
3300: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
3310: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
3320: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
3330: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3340: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3350: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
3360: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3370: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
3380: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
3390: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
33a0: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
33b0: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
33c0: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
33d0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
33e0: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
33f0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
3400: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3410: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
3420: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3430: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3440: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3450: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
3460: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
3470: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
3480: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
3490: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
34a0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
34b0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
34c0: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
34d0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
34e0: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
34f0: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
3500: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
3510: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
3520: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
3530: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3540: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3550: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
3560: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
3570: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
3580: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
3590: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
35a0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
35b0: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
35c0: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
35d0: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
35e0: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
35f0: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c  ss no-op..*/.SQL
3600: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
3610: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3620: 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
3630: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
3640: 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a  e_v2(sqlite3*);.
3650: 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20  ./*.** The type 
3660: 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  for a callback f
3670: 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73  unction..** This
3680: 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64   is legacy and d
3690: 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69  eprecated.  It i
36a0: 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68  s included for h
36b0: 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d  istorical.** com
36c0: 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69  patibility and i
36d0: 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64  s not documented
36e0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74  ..*/.typedef int
36f0: 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62   (*sqlite3_callb
3700: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
3710: 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a  har**, char**);.
3720: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3730: 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20   One-Step Query 
3740: 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66  Execution Interf
3750: 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ace.** METHOD: s
3760: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
3770: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3780: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
3790: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
37a0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
37b0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
37c0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
37d0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
37e0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
37f0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
3800: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
3810: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
3820: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
3830: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3840: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3850: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3860: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3870: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3880: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3890: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
38a0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
38b0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
38c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
38d0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
38e0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
38f0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
3900: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3910: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
3920: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
3930: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3940: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3950: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3960: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3970: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3980: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3990: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
39a0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
39b0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
39c0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
39d0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
39e0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
39f0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3a00: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
3a10: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
3a20: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
3a30: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3a40: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3a50: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3a60: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3a70: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3a80: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3a90: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3aa0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3ab0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3ac0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3ad0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
3ae0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
3af0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3b00: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
3b10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
3b20: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
3b30: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3b40: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3b50: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3b60: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3b70: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3b90: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3ba0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3bb0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3bc0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3bd0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3be0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3bf0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3c00: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
3c10: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
3c20: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
3c30: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3c40: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3c50: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3c60: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3c70: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3c80: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3c90: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3ca0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3cb0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69  meter of.** sqli
3cc0: 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72  te3_exec() after
3cd0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
3ce0: 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20  ge string is no 
3cf0: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a  longer needed..*
3d00: 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61  * ^If the 5th pa
3d10: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
3d20: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
3d30: 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72   NULL and no err
3d40: 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68  ors.** occur, th
3d50: 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  en sqlite3_exec(
3d60: 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74  ) sets the point
3d70: 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61  er in its 5th pa
3d80: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55  rameter to.** NU
3d90: 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  LL before return
3da0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  ing..**.** ^If a
3db0: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3dc0: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
3dd0: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
3de0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3df0: 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
3e00: 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77  s SQLITE_ABORT w
3e10: 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20  ithout invoking 
3e20: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61  the callback aga
3e30: 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75  in and.** withou
3e40: 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75  t running any su
3e50: 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61  bsequent SQL sta
3e60: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
3e70: 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  The 2nd argument
3e80: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3e90: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3ea0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a  function is the.
3eb0: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  ** number of col
3ec0: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
3ed0: 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72  lt.  ^The 3rd ar
3ee0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
3ef0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3f00: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3f10: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3f20: 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61   to strings obta
3f30: 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a  ined as if from.
3f40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
3f50: 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20  mn_text()], one 
3f60: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e  for each column.
3f70: 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74    ^If an element
3f80: 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20   of a.** result 
3f90: 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  row is NULL then
3fa0: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
3fb0: 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  ng string pointe
3fc0: 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c  r for the.** sql
3fd0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3fe0: 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70  back is a NULL p
3ff0: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74  ointer.  ^The 4t
4000: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
4010: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  e.** sqlite3_exe
4020: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  c() callback is 
4030: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
4040: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
4050: 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e  where each.** en
4060: 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74  try represents t
4070: 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65  he name of corre
4080: 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20  sponding result 
4090: 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e  column as obtain
40a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
40b0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
40c0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  )]..**.** ^If th
40d0: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
40e0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
40f0: 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
4100: 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a  ter, a pointer.*
4110: 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  * to an empty st
4120: 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74  ring, or a point
4130: 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  er that contains
4140: 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65   only whitespace
4150: 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20   and/or .** SQL 
4160: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e  comments, then n
4170: 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
4180: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61   are evaluated a
4190: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  nd the database.
41a0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
41b0: 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63  d..**.** Restric
41c0: 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  tions:.**.** <ul
41d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  >.** <li> The ap
41e0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65  plication must e
41f0: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31  nsure that the 1
4200: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4210: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
4220: 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69  *      is a vali
4230: 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61  d and open [data
4240: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
4250: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
4260: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
4270: 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61  ot close the [da
4280: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4290: 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  n] specified by.
42a0: 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20  **      the 1st 
42b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
42c0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
42d0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
42e0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
42f0: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61  <li> The applica
4300: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f  tion must not mo
4310: 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61  dify the SQL sta
4320: 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73  tement text pass
4330: 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20  ed into.**      
4340: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
4350: 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  r of sqlite3_exe
4360: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
4370: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
4380: 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  ing..** </ul>.*/
4390: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
43a0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20  sqlite3_exec(.  
43b0: 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20  sqlite3*,       
43c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43d0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e             /* An
43e0: 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
43f0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
4400: 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  sql,            
4410: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4420: 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
4430: 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28  uated */.  int (
4440: 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  *callback)(void*
4450: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72  ,int,char**,char
4460: 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63  **),  /* Callbac
4470: 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  k function */.  
4480: 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20  void *,         
4490: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44a0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73             /* 1s
44b0: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  t argument to ca
44c0: 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72  llback */.  char
44d0: 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20   **errmsg       
44e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
44f0: 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
4500: 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
4510: 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
4520: 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43  PI3REF: Result C
4530: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4540: 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64  : {result code d
4550: 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a  efinitions}.**.*
4560: 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75  * Many SQLite fu
4570: 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61  nctions return a
4580: 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74  n integer result
4590: 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73   code from the s
45a0: 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65  et shown.** here
45b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64   in order to ind
45c0: 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72  icate success or
45d0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20   failure..**.** 
45e0: 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20  New error codes 
45f0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
4600: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
4610: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
4620: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65   See also: [exte
4630: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4640: 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f   definitions].*/
4650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4660: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
4670: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
4680: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
4690: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
46a0: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
46b0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
46c0: 20 20 20 20 31 20 20 20 2f 2a 20 47 65 6e 65 72      1   /* Gener
46d0: 69 63 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ic error */.#def
46e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
46f0: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
4700: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
4710: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
4720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4730: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
4740: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
4750: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
4760: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
4770: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
4780: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
4790: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
47a0: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
47b0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
47c0: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
47d0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
47e0: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
47f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
4800: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
4810: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
4820: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
4830: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4840: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
4850: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
4860: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
4880: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
4890: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
48a0: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
48b0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
48c0: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
48d0: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
48e0: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
48f0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
4900: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
4910: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
4920: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
4930: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
4940: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
4950: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4960: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
4970: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4980: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
4990: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
49a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
49b0: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
49c0: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20   Unknown opcode 
49d0: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  in sqlite3_file_
49e0: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65  control() */.#de
49f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
4a00: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
4a10: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
4a20: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
4a30: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
4a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
4a50: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
4a60: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
4a70: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
4a80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a90: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
4aa0: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
4ab0: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
4ac0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
4ad0: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
4ae0: 20 20 31 36 20 20 20 2f 2a 20 49 6e 74 65 72 6e    16   /* Intern
4af0: 61 6c 20 75 73 65 20 6f 6e 6c 79 20 2a 2f 0a 23  al use only */.#
4b00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
4b10: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
4b20: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
4b30: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
4b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b50: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
4b60: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
4b70: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
4b80: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
4b90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
4ba0: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
4bb0: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
4bc0: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
4bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4be0: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
4bf0: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
4c00: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
4c10: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
4c20: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
4c30: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
4c40: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
4c50: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
4c60: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
4c70: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
4c80: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
4c90: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
4ca0: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
4cb0: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
4cc0: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
4cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ce0: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
4cf0: 20 2f 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a   /* Not used */.
4d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d10: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
4d20: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
4d30: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
4d40: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
4d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d60: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
4d70: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
4d80: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
4d90: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4db0: 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f  TICE      27   /
4dc0: 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20  * Notifications 
4dd0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4de0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4df0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20  LITE_WARNING    
4e00: 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67   28   /* Warning
4e10: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4e20: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4e30: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20  SQLITE_ROW      
4e40: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74     100  /* sqlit
4e50: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e  e3_step() has an
4e60: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20  other row ready 
4e70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4e80: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30  E_DONE        10
4e90: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  1  /* sqlite3_st
4ea0: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65  ep() has finishe
4eb0: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f  d executing */./
4ec0: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63  * end-of-error-c
4ed0: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  odes */../*.** C
4ee0: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65  API3REF: Extende
4ef0: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
4f00: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
4f10: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4f20: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
4f30: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4f40: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4f50: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4f60: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4f70: 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a  e of 30 integer.
4f80: 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  ** [result codes
4f90: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
4fa0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
4fb0: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
4fc0: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
4fd0: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
4fe0: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
4ff0: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
5000: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
5010: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
5020: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
5030: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
5040: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
5050: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
5060: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
5070: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
5080: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61  ersion 3.3.8 [da
5090: 74 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61  teof:3.3.8].** a
50a0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
50b0: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
50c0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
50d0: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
50e0: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
50f0: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
5100: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
5110: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64   These [extended
5120: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
5130: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
5140: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
5150: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
5160: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
5170: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
5180: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
5190: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
51a0: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64    Or, the extend
51b0: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  ed code for.** t
51c0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
51d0: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61  rror can be obta
51e0: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
51f0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
5200: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23  errcode()]..*/.#
5210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5220: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
5230: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5240: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
5250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5260: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
5270: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5280: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
5290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
52a0: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
52b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
52c0: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
52d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52e0: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  _FSYNC          
52f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5300: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5310: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5320: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  DIR_FSYNC       
5330: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5340: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5350: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
5360: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20  RUNCATE         
5370: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5380: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
5390: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
53a0: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20  TAT             
53b0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
53c0: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
53d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
53e0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
53f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5400: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5410: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
5420: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5430: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
5440: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5450: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
5460: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  E            (SQ
5470: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
5480: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5490: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
54a0: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ED           (SQ
54b0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
54c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54d0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
54e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
54f0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
5500: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5510: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53  LITE_IOERR_ACCES
5520: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  S            (SQ
5530: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33  LITE_IOERR | (13
5540: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5550: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b  LITE_IOERR_CHECK
5560: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51  RESERVEDLOCK (SQ
5570: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34  LITE_IOERR | (14
5580: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5590: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20  LITE_IOERR_LOCK 
55a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
55b0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35  LITE_IOERR | (15
55c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55d0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45  LITE_IOERR_CLOSE
55e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
55f0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36  LITE_IOERR | (16
5600: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5610: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43  LITE_IOERR_DIR_C
5620: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51  LOSE         (SQ
5630: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37  LITE_IOERR | (17
5640: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5650: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50  LITE_IOERR_SHMOP
5660: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51  EN           (SQ
5670: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38  LITE_IOERR | (18
5680: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5690: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49  LITE_IOERR_SHMSI
56a0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ZE           (SQ
56b0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39  LITE_IOERR | (19
56c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56d0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f  LITE_IOERR_SHMLO
56e0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51  CK           (SQ
56f0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30  LITE_IOERR | (20
5700: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5710: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41  LITE_IOERR_SHMMA
5720: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  P            (SQ
5730: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31  LITE_IOERR | (21
5740: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5750: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20  LITE_IOERR_SEEK 
5760: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5770: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32  LITE_IOERR | (22
5780: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5790: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
57a0: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51  E_NOENT      (SQ
57b0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33  LITE_IOERR | (23
57c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
57d0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20  LITE_IOERR_MMAP 
57e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
57f0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34  LITE_IOERR | (24
5800: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5810: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45  LITE_IOERR_GETTE
5820: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51  MPPATH       (SQ
5830: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35  LITE_IOERR | (25
5840: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5850: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50  LITE_IOERR_CONVP
5860: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51  ATH          (SQ
5870: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36  LITE_IOERR | (26
5880: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5890: 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45  LITE_IOERR_VNODE
58a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
58b0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37  LITE_IOERR | (27
58c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58d0: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20  LITE_IOERR_AUTH 
58e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
58f0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38  LITE_IOERR | (28
5900: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5910: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 45 47 49 4e  LITE_IOERR_BEGIN
5920: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 28 53 51  _ATOMIC      (SQ
5930: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 39  LITE_IOERR | (29
5940: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5950: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4d 4d 49  LITE_IOERR_COMMI
5960: 54 5f 41 54 4f 4d 49 43 20 20 20 20 20 28 53 51  T_ATOMIC     (SQ
5970: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 30  LITE_IOERR | (30
5980: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5990: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 4f 4c 4c 42  LITE_IOERR_ROLLB
59a0: 41 43 4b 5f 41 54 4f 4d 49 43 20 20 20 28 53 51  ACK_ATOMIC   (SQ
59b0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 31  LITE_IOERR | (31
59c0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
59d0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52  LITE_LOCKED_SHAR
59e0: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51  EDCACHE      (SQ
59f0: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28  LITE_LOCKED |  (
5a00: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5a10: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56  QLITE_BUSY_RECOV
5a20: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53  ERY           (S
5a30: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
5a40: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5a50: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50  SQLITE_BUSY_SNAP
5a60: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28  SHOT           (
5a70: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
5a80: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5a90: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5aa0: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20  _NOTEMPDIR      
5ab0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5ac0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5ad0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5ae0: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20  EN_ISDIR        
5af0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5b00: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  EN | (2<<8)).#de
5b10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5b20: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20  OPEN_FULLPATH   
5b30: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5b40: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OPEN | (3<<8)).#
5b50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5b60: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20  NTOPEN_CONVPATH 
5b70: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5b80: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29  NTOPEN | (4<<8))
5b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ba0: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5bb0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5bc0: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5bd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5be0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
5bf0: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
5c00: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
5c10: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c20: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
5c30: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5c40: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5c50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c60: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
5c70: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
5c80: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5c90: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5ca0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5cb0: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28  DBMOVED        (
5cc0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5cd0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5ce0: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
5cf0: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
5d00: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
5d10: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5d20: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5d30: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
5d40: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5d50: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
5d60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5d70: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
5d80: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
5d90: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
5da0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5db0: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
5dc0: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
5dd0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
5de0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5df0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5e00: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
5e10: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5e20: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5e30: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5e40: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
5e50: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5e60: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
5e70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5e80: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
5e90: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5ea0: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
5eb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ec0: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
5ed0: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
5ee0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
5ef0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5f00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
5f10: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
5f20: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5f30: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5f40: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5f50: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
5f60: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5f70: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
5f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5f90: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20  TRAINT_ROWID    
5fa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5fb0: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29  TRAINT |(10<<8))
5fc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5fd0: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57  NOTICE_RECOVER_W
5fe0: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  AL      (SQLITE_
5ff0: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29  NOTICE | (1<<8))
6000: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6010: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52  NOTICE_RECOVER_R
6020: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f  OLLBACK (SQLITE_
6030: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29  NOTICE | (2<<8))
6040: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6050: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45  WARNING_AUTOINDE
6060: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  X       (SQLITE_
6070: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29  WARNING | (1<<8)
6080: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
6090: 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20  _AUTH_USER      
60a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
60b0: 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a  _AUTH | (1<<8)).
60c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60d0: 4b 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54  K_LOAD_PERMANENT
60e0: 4c 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f  LY     (SQLITE_O
60f0: 4b 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  K | (1<<8))../*.
6100: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
6110: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
6120: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
6130: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
6140: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
6150: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
6160: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
6170: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
6180: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
6190: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
61a0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
61b0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
61c0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
61d0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
61e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
61f0: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
6200: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
6210: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6220: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6230: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
6240: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
6250: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
6260: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6270: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6280: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
6290: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
62a0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
62b0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
62c0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
62e0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
62f0: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
6300: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6310: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
6320: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
6330: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
6340: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6350: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
6360: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
6370: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
6380: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6390: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
63a0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
63b0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
63c0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
63d0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
63e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
63f0: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
6400: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
6410: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6420: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6430: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6440: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6450: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
6460: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6470: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6480: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6490: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
64a0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
64b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
64c0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
64d0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
64e0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
64f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6500: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6510: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
6520: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6530: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6540: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6550: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6560: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6570: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6580: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
6590: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
65a0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
65b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
65c0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
65d0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
65e0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
65f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
6600: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
6610: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
6620: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6630: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6640: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6650: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6660: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6670: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6680: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6690: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
66a0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
66b0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
66c0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
66d0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
66e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
66f0: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
6700: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
6710: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6720: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6730: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6740: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6750: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6760: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6770: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
6780: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6790: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
67a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
67b0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
67c0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
67d0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
67e0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
67f0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6800: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
6810: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6820: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6830: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6840: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6850: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6860: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6870: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6880: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
6890: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
68a0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
68b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
68c0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
68d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
68e0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
68f0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6900: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6910: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6920: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6930: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6940: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6950: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6960: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6970: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6980: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
6990: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
69a0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
69b0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
69c0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
69d0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
69e0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
69f0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6a00: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6a10: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6a20: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6a30: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6a40: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6a50: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6a60: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6a70: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6a80: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
6a90: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6aa0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
6ab0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
6ac0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
6ad0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
6ae0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6af0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6b00: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
6b10: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6b20: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6b30: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6b40: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6b50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6b60: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6b70: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6b80: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
6b90: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
6ba0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6bb0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
6bc0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
6bd0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
6be0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6bf0: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6c00: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
6c10: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6c20: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
6c30: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6c40: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6c50: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
6c60: 69 63 61 74 65 73 20 74 68 61 74 20 61 20 66 69  icates that a fi
6c70: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c  le cannot be del
6c80: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20  eted when open. 
6c90: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49   The.** SQLITE_I
6ca0: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66  OCAP_IMMUTABLE f
6cb0: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
6cc0: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f  at the file is o
6cd0: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  n.** read-only m
6ce0: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20  edia and cannot 
6cf0: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20  be changed even 
6d00: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74  by processes wit
6d10: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72  h.** elevated pr
6d20: 69 76 69 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20  ivileges..**.** 
6d30: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6d40: 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 20 70 72  _BATCH_ATOMIC pr
6d50: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6d60: 74 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  t the underlying
6d70: 0a 2a 2a 20 66 69 6c 65 73 79 73 74 65 6d 20 73  .** filesystem s
6d80: 75 70 70 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75  upports doing mu
6d90: 6c 74 69 70 6c 65 20 77 72 69 74 65 20 6f 70 65  ltiple write ope
6da0: 72 61 74 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c  rations atomical
6db0: 6c 79 20 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a  ly when those.**
6dc0: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
6dd0: 73 20 61 72 65 20 62 72 61 63 6b 65 74 65 64 20  s are bracketed 
6de0: 62 79 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  by [SQLITE_FCNTL
6df0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52  _BEGIN_ATOMIC_WR
6e00: 49 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c  ITE] and.** [SQL
6e10: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
6e20: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a  _ATOMIC_WRITE]..
6e30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6e40: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
6e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6e60: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
6e70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6e80: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
6e90: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
6ea0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6eb0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
6ec0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6ed0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
6ee0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ef0: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
6f00: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
6f10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6f20: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
6f30: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6f40: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
6f50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6f60: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
6f70: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
6f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6f90: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
6fa0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6fb0: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
6fc0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6fd0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6fe0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
6ff0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
7000: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
7010: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
7020: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
7030: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
7040: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
7050: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
7060: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
7070: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
7080: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
7090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
70a0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
70b0: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
70c0: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
70d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
70e0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
70f0: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
7100: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7110: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
7120: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7130: 32 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  2000.#define SQL
7140: 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f  ITE_IOCAP_BATCH_
7150: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
7160: 20 30 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a   0x00004000../*.
7170: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
7180: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
7190: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
71a0: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
71b0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
71c0: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
71d0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
71e0: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
71f0: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
7200: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
7210: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
7220: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7230: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
7240: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
7250: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
7260: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7270: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
7280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7290: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
72a0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
72b0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
72c0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
72d0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
72e0: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
72f0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
7300: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
7310: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
7320: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
7330: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
7340: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
7350: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7360: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
7370: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
7380: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
7390: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
73a0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
73b0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
73c0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
73d0: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
73e0: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
73f0: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
7400: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
7410: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
7420: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
7430: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
7440: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
7450: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
7460: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
7470: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
7480: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
7490: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
74a0: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
74b0: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
74c0: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
74d0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
74e0: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
74f0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
7500: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
7510: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
7520: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
7530: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
7540: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
7550: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
7560: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
7570: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
7580: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
7590: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
75a0: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
75b0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
75c0: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
75d0: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
75e0: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
75f0: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
7600: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
7610: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
7620: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
7630: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
7640: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
7650: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
7660: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7670: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
7680: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
7690: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
76a0: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
76b0: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
76c0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
76d0: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
76e0: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
76f0: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
7700: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
7710: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
7720: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
7730: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
7740: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
7750: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
7760: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
7770: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
7780: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
7790: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
77a0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
77b0: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
77c0: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
77d0: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
77e0: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
77f0: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
7800: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
7810: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
7820: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
7830: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7840: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
7850: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
7860: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7870: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
7880: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
7890: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
78a0: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
78b0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
78c0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
78d0: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
78e0: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
78f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
7900: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
7910: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
7920: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
7930: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
7940: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
7950: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
7960: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
7970: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
7980: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
7990: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
79a0: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
79b0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
79c0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
79d0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
79e0: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
79f0: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
7a00: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
7a10: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
7a20: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
7a30: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7a40: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
7a50: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
7a60: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
7a70: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
7a80: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
7a90: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
7aa0: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
7ab0: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
7ac0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7ad0: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
7ae0: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
7af0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
7b00: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
7b10: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7b20: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7b30: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
7b40: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7b50: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
7b60: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
7b70: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
7b80: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7b90: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
7ba0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
7bb0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
7bc0: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
7bd0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
7be0: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
7bf0: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
7c00: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
7c10: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
7c20: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
7c30: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7c40: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
7c50: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
7c60: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7c70: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
7c80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
7c90: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
7ca0: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
7cb0: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
7cc0: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
7cd0: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
7ce0: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
7cf0: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
7d00: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7d10: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
7d20: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
7d30: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
7d40: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
7d50: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
7d60: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
7d70: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7d80: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
7d90: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7da0: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
7db0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7dc0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
7dd0: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
7de0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
7df0: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
7e00: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
7e10: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
7e20: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
7e30: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
7e40: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
7e50: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
7e60: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
7e70: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
7e80: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
7e90: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
7ea0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
7eb0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
7ec0: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
7ed0: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
7ee0: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
7ef0: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
7f00: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
7f10: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
7f20: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
7f30: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
7f40: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
7f50: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
7f60: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7f70: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
7f80: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7f90: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
7fa0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
7fb0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
7fc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
7fd0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
7fe0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7ff0: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
8000: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
8010: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
8020: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
8030: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
8040: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
8050: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
8060: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
8070: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
8080: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
8090: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
80a0: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
80b0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
80c0: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
80d0: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
80e0: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
80f0: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
8100: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
8110: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
8120: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
8130: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
8140: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
8150: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
8160: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
8170: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
8180: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
8190: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
81a0: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
81b0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
81c0: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
81d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
81e0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
81f0: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
8200: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
8210: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
8220: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
8230: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
8240: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
8250: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
8260: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
8270: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
8280: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
8290: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
82a0: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
82b0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
82c0: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
82d0: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
82e0: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
82f0: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
8300: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
8310: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
8320: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
8330: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
8340: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
8350: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
8360: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
8370: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
8380: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
8390: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
83a0: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
83b0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
83c0: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
83d0: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
83e0: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
83f0: 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74  .** A [file cont
8400: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69  rol opcodes | li
8410: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
8420: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
8430: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
8440: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
8450: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
8460: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8470: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
8480: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
8490: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
84a0: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20  oid conflicts.  
84b0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
84c0: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ons should.** re
84d0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  turn [SQLITE_NOT
84e0: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20  FOUND] for file 
84f0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
8500: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
8510: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a  .** recognize..*
8520: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
8530: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
8540: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
8550: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
8560: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
8570: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
8580: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
8590: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
85a0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
85b0: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
85c0: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
85d0: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
85e0: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
85f0: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
8600: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
8610: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
8620: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
8630: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
8640: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
8650: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
8660: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
8670: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8680: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
8690: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
86a0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
86b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
86c0: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
86d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
86e0: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
86f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8700: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
8710: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8720: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
8730: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8740: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
8750: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8760: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
8770: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8780: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
8790: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
87a0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
87b0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
87c0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
87d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
87e0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
87f0: 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c  _WHEN_OPEN].** <
8800: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8810: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
8820: 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  WRITE].** <li> [
8830: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
8840: 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  UTABLE].** <li> 
8850: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41  [SQLITE_IOCAP_BA
8860: 54 43 48 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  TCH_ATOMIC].** <
8870: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
8880: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8890: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
88a0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
88b0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
88c0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
88d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
88e0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
88f0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
8900: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
8910: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
8920: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
8930: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
8940: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
8950: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
8960: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
8970: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
8980: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8990: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
89a0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
89b0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
89c0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
89d0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
89e0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
89f0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
8a00: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
8a10: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
8a20: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
8a30: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
8a40: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8a50: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
8a60: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
8a70: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
8a80: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
8a90: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
8aa0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
8ab0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
8ac0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
8ad0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
8ae0: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
8af0: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
8b00: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
8b10: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
8b20: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
8b30: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
8b40: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
8b50: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
8b60: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
8b70: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
8b80: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
8b90: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
8ba0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
8bb0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
8bc0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
8bd0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
8be0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
8bf0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8c00: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
8c10: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
8c20: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
8c30: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
8c40: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8c50: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
8c60: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
8c70: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
8c80: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8c90: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
8ca0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8cb0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
8cc0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8cd0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8ce0: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
8cf0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8d00: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
8d10: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
8d20: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
8d30: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
8d40: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
8d50: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8d60: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8d70: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
8d80: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
8d90: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8da0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
8db0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8dc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
8dd0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
8de0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8df0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
8e00: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
8e10: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
8e20: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
8e30: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
8e40: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
8e50: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8e60: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
8e70: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
8e80: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
8e90: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8ea0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8eb0: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
8ec0: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
8ed0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
8ee0: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
8ef0: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
8f00: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8f10: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8f20: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
8f30: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
8f40: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
8f50: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
8f60: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8f70: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
8f80: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8f90: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
8fa0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8fb0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8fc0: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74  rsion 2 */.  int
8fd0: 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74   (*xFetch)(sqlit
8fe0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8ff0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69  3_int64 iOfst, i
9000: 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a  nt iAmt, void **
9010: 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  pp);.  int (*xUn
9020: 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  fetch)(sqlite3_f
9030: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
9040: 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20  t64 iOfst, void 
9050: 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  *p);.  /* Method
9060: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
9070: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  d for version 3 
9080: 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  */.  /* Addition
9090: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
90a0: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
90b0: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
90c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
90d0: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
90e0: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a  Control Opcodes.
90f0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69  ** KEYWORDS: {fi
9100: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
9110: 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f  es} {file contro
9120: 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20  l opcode}.**.** 
9130: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
9140: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
9150: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
9160: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
9170: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
9180: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
9190: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
91a0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
91b0: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
91c0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c  terface..**.** <
91d0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  ul>.** <li>[[SQL
91e0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
91f0: 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ATE]].** The [SQ
9200: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
9210: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
9220: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
9230: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
9240: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
9250: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
9260: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20  od to write the 
9270: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66  current state of
9280: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e  .** the lock (on
9290: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  e of [SQLITE_LOC
92a0: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  K_NONE], [SQLITE
92b0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
92c0: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  * [SQLITE_LOCK_R
92d0: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54  ESERVED], [SQLIT
92e0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
92f0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   or [SQLITE_LOCK
9300: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20  _EXCLUSIVE]).** 
9310: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  into an integer 
9320: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72  that the pArg ar
9330: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
9340: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74  . This capabilit
9350: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72  y.** is used dur
9360: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20  ing testing and 
9370: 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
9380: 65 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54  e when the SQLIT
9390: 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c  E_TEST.** compil
93a0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
93b0: 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   used..**.** <li
93c0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
93d0: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
93e0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
93f0: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
9400: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
9410: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
9420: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
9430: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
9440: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
9450: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
9460: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
9470: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
9480: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
9490: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
94a0: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
94b0: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
94c0: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
94d0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
94e0: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
94f0: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
9500: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
9510: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
9520: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
9530: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
9540: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
9550: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
9560: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
9570: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
9580: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
9590: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
95a0: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
95b0: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
95c0: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
95d0: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
95e0: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
95f0: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
9600: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
9610: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
9620: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
9630: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
9640: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9650: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
9660: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
9670: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
9680: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
9690: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
96a0: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
96b0: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
96c0: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
96d0: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
96e0: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
96f0: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
9700: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
9710: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
9720: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
9730: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
9740: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
9750: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
9760: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9770: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9780: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
9790: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
97a0: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
97b0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
97c0: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
97d0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
97e0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
97f0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
9800: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
9810: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9820: 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51  n.  See also [SQ
9830: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9840: 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a  AL_POINTER]..**.
9850: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9860: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
9870: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
9880: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55  SQLITE_FCNTL_JOU
9890: 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  RNAL_POINTER] op
98a0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
98b0: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
98c0: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
98d0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
98e0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
98f0: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c   the journal fil
9900: 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65  e (either.** the
9910: 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e   [rollback journ
9920: 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74  al] or the [writ
9930: 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f  e-ahead log]) fo
9940: 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  r a particular d
9950: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
9960: 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f  ction.  See also
9970: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46   [SQLITE_FCNTL_F
9980: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a  ILE_POINTER]..**
9990: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
99a0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
99b0: 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67  TED]].** No long
99c0: 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a  er in use..**.**
99d0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
99e0: 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68  NTL_SYNC]].** Th
99f0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9a00: 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20  SYNC] opcode is 
9a10: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
9a20: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61  ally by SQLite a
9a30: 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68  nd.** sent to th
9a40: 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c  e VFS immediatel
9a50: 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79  y before the xSy
9a60: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  nc method is inv
9a70: 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74  oked on a.** dat
9a80: 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72  abase file descr
9a90: 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68  iptor. Or, if th
9aa0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
9ab0: 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a  s not invoked .*
9ac0: 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73  * because the us
9ad0: 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65  er has configure
9ae0: 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a  d SQLite with .*
9af0: 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  * [PRAGMA synchr
9b00: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73  onous | PRAGMA s
9b10: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20  ynchronous=OFF] 
9b20: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e  it is invoked in
9b30: 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68   place .** of th
9b40: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20  e xSync method. 
9b50: 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74  In most cases, t
9b60: 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
9b70: 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a  ent passed with.
9b80: 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  ** this file-con
9b90: 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f  trol is NULL. Ho
9ba0: 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61  wever, if the da
9bb0: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62  tabase file is b
9bc0: 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61  eing synced.** a
9bd0: 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74  s part of a mult
9be0: 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69  i-database commi
9bf0: 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  t, the argument 
9c00: 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d  points to a nul-
9c10: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
9c20: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
9c30: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  the transactions
9c40: 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20   master-journal 
9c50: 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73  file name. VFSes
9c60: 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74   that .** do not
9c70: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9c80: 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  l should silentl
9c90: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
9ca0: 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f  code. Applicatio
9cb0: 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f  ns .** should no
9cc0: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
9cd0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9ce0: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65  with this opcode
9cf0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
9d00: 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65   .** disrupt the
9d10: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
9d20: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
9d30: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75  Ses that do requ
9d40: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20  ire it.  .**.** 
9d50: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9d60: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9d70: 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  WO]].** The [SQL
9d80: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
9d90: 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64  _PHASETWO] opcod
9da0: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
9db0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
9dc0: 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20  ite.** and sent 
9dd0: 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72  to the VFS after
9de0: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68   a transaction h
9df0: 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65  as been committe
9e00: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a  d immediately.**
9e10: 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20   but before the 
9e20: 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f  database is unlo
9e30: 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74  cked. VFSes that
9e40: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
9e50: 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75  s signal.** shou
9e60: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9e70: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
9e80: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
9e90: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20  uld not call.** 
9ea0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9eb0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9ec0: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9ed0: 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70  ng so may disrup
9ee0: 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74  t the .** operat
9ef0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
9f00: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
9f10: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9f20: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
9f30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9f40: 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20  2_AV_RETRY]].** 
9f50: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9f60: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
9f70: 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  Y] opcode is use
9f80: 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61  d to configure a
9f90: 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72  utomatic.** retr
9fa0: 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74  y counts and int
9fb0: 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61  ervals for certa
9fc0: 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72  in disk I/O oper
9fd0: 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a  ations for the.*
9fe0: 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20  * windows [VFS] 
9ff0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76  in order to prov
a000: 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69  ide robustness i
a010: 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  n the presence o
a020: 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20  f.** anti-virus 
a030: 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65  programs.  By de
a040: 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f  fault, the windo
a050: 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72  ws VFS will retr
a060: 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20  y file read,.** 
a070: 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20  file write, and 
a080: 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72  file delete oper
a090: 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20  ations up to 10 
a0a0: 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65  times, with a de
a0b0: 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c  lay.** of 25 mil
a0c0: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65  liseconds before
a0d0: 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79   the first retry
a0e0: 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65   and with the de
a0f0: 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a  lay increasing.*
a100: 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e  * by an addition
a110: 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  al 25 millisecon
a120: 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62  ds with each sub
a130: 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20  sequent retry.  
a140: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  This.** opcode a
a150: 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20  llows these two 
a160: 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69  values (10 retri
a170: 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73  es and 25 millis
a180: 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29  econds of delay)
a190: 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74  .** to be adjust
a1a0: 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20  ed.  The values 
a1b0: 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20  are changed for 
a1c0: 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e  all database con
a1d0: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  nections.** with
a1e0: 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63  in the same proc
a1f0: 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ess.  The argume
a200: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
a210: 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74  to an array of t
a220: 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77  wo.** integers w
a230: 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69  here the first i
a240: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 6e 65  nteger is the ne
a250: 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e  w retry count an
a260: 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  d the second.** 
a270: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64  integer is the d
a280: 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72  elay.  If either
a290: 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61   integer is nega
a2a0: 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73  tive, then the s
a2b0: 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74  etting.** is not
a2c0: 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73   changed but ins
a2d0: 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76  tead the prior v
a2e0: 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74  alue of that set
a2f0: 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a  ting is written.
a300: 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61  ** into the arra
a310: 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e  y entry, allowin
a320: 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  g the current re
a330: 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20  try settings to 
a340: 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74  be.** interrogat
a350: 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65  ed.  The zDbName
a360: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67   parameter is ig
a370: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  nored..**.** <li
a380: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a390: 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a  PERSIST_WAL]].**
a3a0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a3b0: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
a3c0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
a3d0: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
a3e0: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
a3f0: 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41  t [WAL | Write A
a400: 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e  head Log] settin
a410: 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  g.  By default, 
a420: 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a  the auxiliary.**
a430: 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67   write ahead log
a440: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
a450: 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f  ry files used fo
a460: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  r transaction co
a470: 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74  ntrol.** are aut
a480: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
a490: 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65  ed when the late
a4a0: 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  st connection to
a4b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
a4c0: 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e   closes.  Settin
a4d0: 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  g persistent WAL
a4e0: 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f   mode causes tho
a4f0: 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73  se files to pers
a500: 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f  ist after.** clo
a510: 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20  se.  Persisting 
a520: 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65  the files is use
a530: 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70  ful when other p
a540: 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f  rocesses that do
a550: 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69   not.** have wri
a560: 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e  te permission on
a570: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63   the directory c
a580: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61  ontaining the da
a590: 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74  tabase file want
a5a0: 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20  .** to read the 
a5b0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61  database file, a
a5c0: 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68  s the WAL and sh
a5d0: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
a5e0: 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20  s must exist.** 
a5f0: 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65  in order for the
a600: 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   database to be 
a610: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66  readable.  The f
a620: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a630: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a640: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a650: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a660: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a670: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
a680: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
a690: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
a6a0: 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  e persistent WAL
a6b0: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
a6c0: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a  able persistent.
a6d0: 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66  ** WAL mode.  If
a6e0: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
a6f0: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
a700: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
a710: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57  the current.** W
a720: 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73  AL persistence s
a730: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
a740: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a750: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a760: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a770: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
a780: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a790: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a7a0: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
a7b0: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
a7c0: 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76  nt "powersafe-ov
a7d0: 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f  erwrite" or "PSO
a7e0: 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65  W" setting.  The
a7f0: 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a   PSOW setting.**
a800: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
a810: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
a820: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a830: 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a  E] bit of the.**
a840: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
a850: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e  ristics methods.
a860: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
a870: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
a880: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a890: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
a8a0: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
a8b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
a8c0: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
a8d0: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
a8e0: 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d  disable zero-dam
a8f0: 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  age mode or 1 to
a900: 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d   enable zero-dam
a910: 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66  age.** mode.  If
a920: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
a930: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
a940: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
a950: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a  the current.** z
a960: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
a970: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
a980: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a990: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  L_OVERWRITE]].**
a9a0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a9b0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  NTL_OVERWRITE] o
a9c0: 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64  pcode is invoked
a9d0: 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72   by SQLite after
a9e0: 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72   opening.** a wr
a9f0: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ite transaction 
aa00: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
aa10: 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72  , unless it is r
aa20: 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73  olled back for s
aa30: 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74  ome.** reason, t
aa40: 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61  he entire databa
aa50: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  se file will be 
aa60: 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
aa70: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74  he current .** t
aa80: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73  ransaction. This
aa90: 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55   is used by VACU
aaa0: 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  UM operations..*
aab0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
aac0: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
aad0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
aae0: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
aaf0: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
ab00: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
ab10: 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c  e names of.** al
ab20: 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65  l [VFSes] in the
ab30: 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65   VFS stack.  The
ab40: 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c   names are of al
ab50: 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20  l VFS shims and 
ab60: 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74  the.** final bot
ab70: 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72  tom-level VFS ar
ab80: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  e written into m
ab90: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
aba0: 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
abb0: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74  _malloc()] and t
abc0: 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f  he result is sto
abd0: 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a  red in the char*
abe0: 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61   variable.** tha
abf0: 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  t the fourth par
ac00: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74  ameter of [sqlit
ac10: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
ac20: 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a  )] points to..**
ac30: 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72   The caller is r
ac40: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66  esponsible for f
ac50: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72  reeing the memor
ac60: 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73  y when done.  As
ac70: 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c   with.** all fil
ac80: 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e  e-control action
ac90: 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67  s, there is no g
aca0: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
acb0: 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79  is will actually
acc0: 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e  .** do anything.
acd0: 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64    Callers should
ace0: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
acf0: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74  char* variable t
ad00: 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  o a NULL.** poin
ad10: 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73  ter in case this
ad20: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
ad30: 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
ad40: 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e  .  This file-con
ad50: 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e  trol.** is inten
ad60: 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74  ded for diagnost
ad70: 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a  ic use only..**.
ad80: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ad90: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
ada0: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
adb0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
adc0: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69  INTER] opcode fi
add0: 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  nds a pointer to
ade0: 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a   the top-level.*
adf0: 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e  * [VFSes] curren
ae00: 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54  tly in use.  ^(T
ae10: 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e  he argument X in
ae20: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  .** sqlite3_file
ae30: 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49  _control(db,SQLI
ae40: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
ae50: 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a  NTER,X) must be.
ae60: 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c  ** of type "[sql
ae70: 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20  ite3_vfs] **".  
ae80: 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c  This opcodes wil
ae90: 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61  l set *X.** to a
aea0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
aeb0: 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e  top-level VFS.)^
aec0: 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20  .** ^When there 
aed0: 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53  are multiple VFS
aee0: 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74   shims in the st
aef0: 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65  ack, this opcode
af00: 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70   finds the.** up
af10: 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e  per-most shim on
af20: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
af30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
af40: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
af50: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
af60: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
af70: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
af80: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
af90: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
afa0: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
afb0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
afc0: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
afd0: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
afe0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
aff0: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
b000: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
b010: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
b020: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
b030: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b040: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
b050: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
b060: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
b070: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
b080: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
b090: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
b0a0: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
b0b0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
b0c0: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
b0d0: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
b0e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
b0f0: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
b100: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
b110: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
b120: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
b130: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
b140: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
b150: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
b160: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
b170: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
b180: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
b190: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
b1a0: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
b1b0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
b1c0: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
b1d0: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
b1e0: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
b1f0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
b200: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
b210: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
b220: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
b230: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
b240: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
b250: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
b260: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
b270: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
b280: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
b290: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
b2a0: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
b2b0: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
b2c0: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
b2d0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
b2e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
b2f0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
b300: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
b310: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
b320: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
b330: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
b340: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
b350: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
b360: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
b370: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
b380: 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  if result string
b390: 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61   is NULL, or tha
b3a0: 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  t returns a copy
b3b0: 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
b3c0: 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 20  t string if the 
b3d0: 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55  string is non-NU
b3e0: 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  LL..** ^If the [
b3f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b400: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
b410: 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  l returns.** any
b420: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68   result code oth
b430: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
b440: 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  OK] or [SQLITE_N
b450: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d  OTFOUND], that m
b460: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  eans.** that the
b470: 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64   VFS encountered
b480: 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20   an error while 
b490: 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52  handling the [PR
b4a0: 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  AGMA] and the.**
b4b0: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20   compilation of 
b4c0: 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73  the PRAGMA fails
b4d0: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
b4e0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
b4f0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
b500: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75  ile control occu
b510: 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e  rs at the beginn
b520: 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74  ing of pragma st
b530: 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73  atement analysis
b540: 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73   and so.** it is
b550: 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64   able to overrid
b560: 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47  e built-in [PRAG
b570: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  MA] statements..
b580: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b590: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b5a0: 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  DLER]].** ^The [
b5b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b5c0: 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c  YHANDLER].** fil
b5d0: 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65  e-control may be
b5e0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
b5f0: 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  te on the databa
b600: 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a  se file handle.*
b610: 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20  * shortly after 
b620: 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  it is opened in 
b630: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
b640: 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69   a custom VFS wi
b650: 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  th access.** to 
b660: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  the connections 
b670: 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
b680: 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d  lback. The argum
b690: 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28  ent is of type (
b6a0: 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e  void **).** - an
b6b0: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76   array of two (v
b6c0: 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54  oid *) values. T
b6d0: 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a  he first (void *
b6e0: 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74  ) actually point
b6f0: 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69  s.** to a functi
b700: 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20  on of type (int 
b710: 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e  (*)(void *)). In
b720: 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65   order to invoke
b730: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
b740: 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  .** busy-handler
b750: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
b760: 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65  should be invoke
b770: 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e  d with the secon
b780: 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a  d (void *) in.**
b790: 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68   the array as th
b7a0: 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e  e only argument.
b7b0: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e   If it returns n
b7c0: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
b7d0: 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73  e operation.** s
b7e0: 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64  hould be retried
b7f0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
b800: 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d  zero, the custom
b810: 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e   VFS should aban
b820: 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  don the.** curre
b830: 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a  nt operation..**
b840: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b850: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
b860: 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63  AME]].** ^Applic
b870: 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65  ation can invoke
b880: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
b890: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
b8a0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
b8b0: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20   to have SQLite 
b8c0: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65  generate a.** te
b8d0: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
b8e0: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
b8f0: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69  algorithm that i
b900: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65  s followed to ge
b910: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  nerate.** tempor
b920: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f  ary filenames fo
b930: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e  r TEMP tables an
b940: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  d other internal
b950: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61   uses.  The.** a
b960: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
b970: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68  e a char** which
b980: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20   will be filled 
b990: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d  with the filenam
b9a0: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74  e.** written int
b9b0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
b9c0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
b9d0: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
b9e0: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a  caller should.**
b9f0: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
ba00: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20  _free()] on the 
ba10: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20  result to avoid 
ba20: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a  a memory leak..*
ba30: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ba40: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
ba50: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
ba60: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
ba70: 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
ba80: 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72   is used to quer
ba90: 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20  y or set the.** 
baa0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
bab0: 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c  f bytes that wil
bac0: 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65  l be used for me
bad0: 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e  mory-mapped I/O.
bae0: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
baf0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
bb00: 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65   a value of type
bb10: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74   sqlite3_int64 t
bb20: 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76  hat.** is an adv
bb30: 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75  isory maximum nu
bb40: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
bb50: 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d   the file to mem
bb60: 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a  ory map.  The.**
bb70: 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72   pointer is over
bb80: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
bb90: 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65   old value.  The
bba0: 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68   limit is not ch
bbb0: 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20  anged if.** the 
bbc0: 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79  value originally
bbd0: 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e   pointed to is n
bbe0: 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20  egative, and so 
bbf0: 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69  the current limi
bc00: 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65  t .** can be que
bc10: 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ried by passing 
bc20: 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  in a pointer to 
bc30: 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
bc40: 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65  r.  This.** file
bc50: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64  -control is used
bc60: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69   internally to i
bc70: 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41  mplement [PRAGMA
bc80: 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a   mmap_size]..**.
bc90: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bca0: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a  FCNTL_TRACE]].**
bcb0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
bcc0: 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63  TL_TRACE] file c
bcd0: 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20  ontrol provides 
bce0: 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61  advisory informa
bcf0: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56  tion.** to the V
bd00: 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68  FS about what th
bd10: 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20  e higher layers 
bd20: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74  of the SQLite st
bd30: 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a  ack are doing..*
bd40: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  * This file cont
bd50: 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73  rol is used by s
bd60: 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79  ome VFS activity
bd70: 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d   tracing [shims]
bd80: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
bd90: 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t is a zero-term
bda0: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20  inated string.  
bdb0: 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e  Higher layers in
bdc0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73   the.** SQLite s
bdd0: 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74  tack may generat
bde0: 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74  e instances of t
bdf0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
be00: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49   if.** the [SQLI
be10: 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41  TE_USE_FCNTL_TRA
be20: 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
be30: 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
be40: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
be50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
be60: 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20  _MOVED]].** The 
be70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
be80: 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f  S_MOVED] file co
be90: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73  ntrol interprets
bea0: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73   its argument as
beb0: 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
bec0: 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20   an integer and 
bed0: 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c  it writes a bool
bee0: 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  ean into that in
bef0: 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a  teger depending.
bf00: 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72  ** on whether or
bf10: 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61   not the file ha
bf20: 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20  s been renamed, 
bf30: 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65  moved, or delete
bf40: 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61  d since it.** wa
bf50: 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a  s first opened..
bf60: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bf70: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47  TE_FCNTL_WIN32_G
bf80: 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54  ET_HANDLE]].** T
bf90: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
bfa0: 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c  _WIN32_GET_HANDL
bfb0: 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65  E] opcode can be
bfc0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
bfd0: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
bfe0: 67 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61  g native file ha
bff0: 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20  ndle associated 
c000: 77 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e 64  with a file hand
c010: 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a 2a  le.  This file.*
c020: 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  * control interp
c030: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
c040: 74 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t as a pointer t
c050: 6f 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65 20  o a native file 
c060: 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72  handle and.** wr
c070: 69 74 65 73 20 74 68 65 20 72 65 73 75 6c 74 69  ites the resulti
c080: 6e 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e 0a  ng value there..
c090: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c0a0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
c0b0: 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54  ET_HANDLE]].** T
c0c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c0d0: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
c0e0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
c0f0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
c100: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
c110: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
c120: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
c130: 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c 65  to swap the file
c140: 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65   handle with the
c150: 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20   one.** pointed 
c160: 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 61  to by the pArg a
c170: 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63  rgument.  This c
c180: 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 65  apability is use
c190: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
c1a0: 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  .** and only nee
c1b0: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
c1c0: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
c1d0: 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  EST is defined..
c1e0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c1f0: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
c200: 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CK]].** The [SQL
c210: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
c220: 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c  OCK] is a signal
c230: 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65   to the VFS laye
c240: 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a  r that it might.
c250: 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f  ** be advantageo
c260: 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74  us to block on t
c270: 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b  he next WAL lock
c280: 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20   if the lock is 
c290: 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  not immediately.
c2a0: 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54  ** available.  T
c2b0: 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d  he WAL subsystem
c2c0: 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69 67   issues this sig
c2d0: 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a  nal during rare.
c2e0: 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  ** circumstances
c2f0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78   in order to fix
c300: 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20   a problem with 
c310: 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69  priority inversi
c320: 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  on..** Applicati
c330: 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e  ons should <em>n
c340: 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73  ot</em> use this
c350: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a   file-control..*
c360: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c370: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d  E_FCNTL_ZIPVFS]]
c380: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c390: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70  FCNTL_ZIPVFS] op
c3a0: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
c3b0: 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e  ted by zipvfs on
c3c0: 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a  ly. All other.**
c3d0: 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75   VFS should retu
c3e0: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
c3f0: 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  ND for this opco
c400: 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  de..**.** <li>[[
c410: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c420: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
c430: 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63  E_FCNTL_RBU] opc
c440: 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ode is implement
c450: 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69 61  ed by the specia
c460: 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a  l VFS used by.**
c470: 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73 69   the RBU extensi
c480: 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74  on only.  All ot
c490: 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72  her VFS should r
c4a0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54  eturn SQLITE_NOT
c4b0: 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69  FOUND for.** thi
c4c0: 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a  s opcode.  .**.*
c4d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c4e0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
c4f0: 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66 20  C_WRITE]].** If 
c500: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
c510: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
c520: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 72 65 74  RITE] opcode ret
c530: 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2c 20  urns SQLITE_OK, 
c540: 74 68 65 6e 0a 2a 2a 20 74 68 65 20 66 69 6c 65  then.** the file
c550: 20 64 65 73 63 72 69 70 74 6f 72 20 69 73 20 70   descriptor is p
c560: 6c 61 63 65 64 20 69 6e 20 22 62 61 74 63 68 20  laced in "batch 
c570: 77 72 69 74 65 20 6d 6f 64 65 22 2c 20 77 68 69  write mode", whi
c580: 63 68 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c 20  ch.** means all 
c590: 73 75 62 73 65 71 75 65 6e 74 20 77 72 69 74 65  subsequent write
c5a0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 69 6c 6c   operations will
c5b0: 20 62 65 20 64 65 66 65 72 72 65 64 20 61 6e 64   be deferred and
c5c0: 20 64 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63 61   done.** atomica
c5d0: 6c 6c 79 20 61 74 20 74 68 65 20 6e 65 78 74 20  lly at the next 
c5e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
c5f0: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
c600: 45 5d 2e 20 20 53 79 73 74 65 6d 73 0a 2a 2a 20  E].  Systems.** 
c610: 74 68 61 74 20 64 6f 20 6e 6f 74 20 73 75 70 70  that do not supp
c620: 6f 72 74 20 62 61 74 63 68 20 61 74 6f 6d 69 63  ort batch atomic
c630: 20 77 72 69 74 65 73 20 77 69 6c 6c 20 72 65 74   writes will ret
c640: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
c650: 55 4e 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69  UND..** ^Followi
c660: 6e 67 20 61 20 73 75 63 63 65 73 73 66 75 6c 20  ng a successful 
c670: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47  SQLITE_FCNTL_BEG
c680: 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20  IN_ATOMIC_WRITE 
c690: 61 6e 64 20 70 72 69 6f 72 20 74 6f 0a 2a 2a 20  and prior to.** 
c6a0: 74 68 65 20 63 6c 6f 73 69 6e 67 20 5b 53 51 4c  the closing [SQL
c6b0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
c6c0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f  _ATOMIC_WRITE] o
c6d0: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  r.** [SQLITE_FCN
c6e0: 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d  TL_ROLLBACK_ATOM
c6f0: 49 43 5f 57 52 49 54 45 5d 2c 20 53 51 4c 69 74  IC_WRITE], SQLit
c700: 65 20 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e  e will make.** n
c710: 6f 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20  o VFS interface 
c720: 63 61 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61 6d  calls on the sam
c730: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
c740: 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72   file descriptor
c750: 0a 2a 2a 20 65 78 63 65 70 74 20 66 6f 72 20 63  .** except for c
c760: 61 6c 6c 73 20 74 6f 20 74 68 65 20 78 57 72 69  alls to the xWri
c770: 74 65 20 6d 65 74 68 6f 64 20 61 6e 64 20 74 68  te method and th
c780: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
c790: 65 74 68 6f 64 0a 2a 2a 20 77 69 74 68 20 5b 53  ethod.** with [S
c7a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
c7b0: 5f 48 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  _HINT]..**.** <l
c7c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c7d0: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57  _COMMIT_ATOMIC_W
c7e0: 52 49 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  RITE]].** The [S
c7f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
c800: 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  IT_ATOMIC_WRITE]
c810: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 61   opcode causes a
c820: 6c 6c 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72  ll write.** oper
c830: 61 74 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65  ations since the
c840: 20 70 72 65 76 69 6f 75 73 20 73 75 63 63 65 73   previous succes
c850: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a  sful call to .**
c860: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
c870: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
c880: 45 5d 20 74 6f 20 62 65 20 70 65 72 66 6f 72 6d  E] to be perform
c890: 65 64 20 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a  ed atomically..*
c8a0: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  * This file cont
c8b0: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
c8c0: 49 54 45 5f 4f 4b 5d 20 69 66 20 61 6e 64 20 6f  ITE_OK] if and o
c8d0: 6e 6c 79 20 69 66 20 74 68 65 20 77 72 69 74 65  nly if the write
c8e0: 73 20 77 65 72 65 0a 2a 2a 20 61 6c 6c 20 70 65  s were.** all pe
c8f0: 72 66 6f 72 6d 65 64 20 73 75 63 63 65 73 73 66  rformed successf
c900: 75 6c 6c 79 20 61 6e 64 20 68 61 76 65 20 62 65  ully and have be
c910: 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 74 6f 20  en committed to 
c920: 70 65 72 73 69 73 74 65 6e 74 20 73 74 6f 72 61  persistent stora
c930: 67 65 2e 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  ge..** ^Regardle
c940: 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
c950: 20 6e 6f 74 20 69 74 20 69 73 20 73 75 63 63 65   not it is succe
c960: 73 73 66 75 6c 2c 20 74 68 69 73 20 66 69 6c 65  ssful, this file
c970: 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 0a 2a   control takes.*
c980: 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72  * the file descr
c990: 69 70 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74  iptor out of bat
c9a0: 63 68 20 77 72 69 74 65 20 6d 6f 64 65 20 73 6f  ch write mode so
c9b0: 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 71   that all subseq
c9c0: 75 65 6e 74 0a 2a 2a 20 77 72 69 74 65 20 6f 70  uent.** write op
c9d0: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64  erations are ind
c9e0: 65 70 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51  ependent..** ^SQ
c9f0: 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
ca00: 69 6e 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43  invoke SQLITE_FC
ca10: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
ca20: 43 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a  C_WRITE without.
ca30: 2a 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  ** a prior succe
ca40: 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53  ssful call to [S
ca50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
ca60: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e  N_ATOMIC_WRITE].
ca70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
ca80: 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41  ITE_FCNTL_ROLLBA
ca90: 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d  CK_ATOMIC_WRITE]
caa0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
cab0: 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f  _FCNTL_ROLLBACK_
cac0: 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70  ATOMIC_WRITE] op
cad0: 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20  code causes all 
cae0: 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69  write.** operati
caf0: 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 72  ons since the pr
cb00: 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 75  evious successfu
cb10: 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53  l call to .** [S
cb20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
cb30: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
cb40: 74 6f 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  to be rolled bac
cb50: 6b 2e 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65  k..** ^This file
cb60: 20 63 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 20 74   control takes t
cb70: 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74  he file descript
cb80: 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20  or out of batch 
cb90: 77 72 69 74 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f  write mode.** so
cba0: 20 74 68 61 74 20 61 6c 6c 20 73 75 62 73 65 71   that all subseq
cbb0: 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61  uent write opera
cbc0: 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65  tions are indepe
cbd0: 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ndent..** ^SQLit
cbe0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
cbf0: 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  oke SQLITE_FCNTL
cc00: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
cc10: 5f 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a  _WRITE without.*
cc20: 2a 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  * a prior succes
cc30: 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51  sful call to [SQ
cc40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
cc50: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a  _ATOMIC_WRITE]..
cc60: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
cc70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cc80: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
cc90: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
cca0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ccb0: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
ccc0: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  E       2.#defin
ccd0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
cce0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
ccf0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
cd00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
cd10: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
cd20: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
cd30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
cd40: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
cd50: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
cd60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
cd70: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
cd80: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
cd90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
cda0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
cdb0: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
cdc0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
cdd0: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
cde0: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
cdf0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
ce00: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
ce10: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
ce20: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
ce30: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
ce40: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
ce50: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
ce60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
ce70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ce80: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
ce90: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
cea0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ceb0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
cec0: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
ced0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cee0: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
cef0: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
cf00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
cf10: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
cf20: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
cf30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
cf40: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
cf50: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
cf60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
cf70: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
cf80: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
cf90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cfa0: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
cfb0: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
cfc0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
cfd0: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
cfe0: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
cff0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
d000: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
d010: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
d020: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
d030: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
d040: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
d050: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
d060: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
d070: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51     23.#define SQ
d080: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
d090: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
d0a0: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    24.#define SQL
d0b0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
d0c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d0d0: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   25.#define SQLI
d0e0: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20  TE_FCNTL_RBU    
d0f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d100: 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  26.#define SQLIT
d110: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
d120: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32  TER            2
d130: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
d140: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
d150: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38  OINTER        28
d160: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d170: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
d180: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a  HANDLE       29.
d190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d1a0: 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20  CNTL_PDB        
d1b0: 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 23              30.#
d1c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d1d0: 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43  NTL_BEGIN_ATOMIC
d1e0: 5f 57 52 49 54 45 20 20 20 20 20 33 31 0a 23 64  _WRITE     31.#d
d1f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d200: 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43  TL_COMMIT_ATOMIC
d210: 5f 57 52 49 54 45 20 20 20 20 33 32 0a 23 64 65  _WRITE    32.#de
d220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d230: 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49  L_ROLLBACK_ATOMI
d240: 43 5f 57 52 49 54 45 20 20 33 33 0a 0a 2f 2a 20  C_WRITE  33../* 
d250: 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73  deprecated names
d260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
d270: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
d280: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
d290: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
d2a0: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
d2b0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
d2c0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
d2d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
d2e0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
d2f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
d300: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
d310: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
d320: 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a  _LAST_ERRNO.../*
d330: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
d340: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
d350: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
d360: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
d370: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
d380: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
d390: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
d3a0: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
d3b0: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
d3c0: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
d3d0: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
d3e0: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
d3f0: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
d400: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
d410: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
d420: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
d430: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
d440: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
d450: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
d460: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
d470: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
d480: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
d490: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
d4a0: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
d4b0: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
d4c0: 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74  EF: Loadable Ext
d4d0: 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a  ension Thunk.**.
d4e0: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
d4f0: 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74  the opaque sqlit
d500: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
d510: 73 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73  structure is pas
d520: 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68  sed as.** the th
d530: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
d540: 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66   entry points of
d550: 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e   [loadable exten
d560: 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a  sions].  This.**
d570: 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
d580: 62 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20  be typedefed in 
d590: 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72  order to work ar
d5a0: 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61  ound compiler wa
d5b0: 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d  rnings.** on som
d5c0: 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a  e platforms..*/.
d5d0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
d5e0: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
d5f0: 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  nes sqlite3_api_
d600: 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a  routines;../*.**
d610: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
d620: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
d630: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
d640: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
d650: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
d660: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
d670: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
d680: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
d690: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
d6a0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
d6b0: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
d6c0: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
d6d0: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
d6e0: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
d6f0: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
d700: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
d710: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
d720: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
d730: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
d740: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
d750: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
d760: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
d770: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
d780: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
d790: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
d7a0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
d7b0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
d7c0: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
d7d0: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
d7e0: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
d7f0: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
d800: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
d810: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
d820: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
d830: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
d840: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
d850: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
d860: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
d870: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
d880: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
d890: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
d8a0: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
d8b0: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
d8c0: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
d8d0: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
d8e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
d8f0: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
d900: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
d910: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
d920: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
d930: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
d940: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
d950: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
d960: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
d970: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
d980: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
d990: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
d9a0: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
d9b0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
d9c0: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
d9d0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
d9e0: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
d9f0: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
da00: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
da10: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
da20: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
da30: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
da40: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
da50: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
da60: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
da70: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
da80: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
da90: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
daa0: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
dab0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
dac0: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
dad0: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
dae0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
daf0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
db00: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
db10: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
db20: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
db30: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
db40: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
db50: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
db60: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
db70: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
db80: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
db90: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
dba0: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
dbb0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
dbc0: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
dbd0: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
dbe0: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
dbf0: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
dc00: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
dc10: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
dc20: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
dc30: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
dc40: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
dc50: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73  dules..**.** [[s
dc60: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
dc70: 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  ]].** ^SQLite gu
dc80: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
dc90: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
dca0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
dcb0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
dcc0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
dcd0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
dce0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
dcf0: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
dd00: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
dd10: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
dd20: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
dd30: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
dd40: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
dd50: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
dd60: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
dd70: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
dd80: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
dd90: 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72  ** 11 alphanumer
dda0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
ddb0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
ddc0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
ddd0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
dde0: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
ddf0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
de00: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
de10: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
de20: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
de30: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
de40: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
de50: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
de60: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
de70: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
de80: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
de90: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
dea0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
deb0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
dec0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
ded0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
dee0: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
def0: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
df00: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
df10: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
df20: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
df30: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
df40: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
df50: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
df60: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
df70: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
df80: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
df90: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
dfa0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
dfb0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
dfc0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
dfd0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
dfe0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
dff0: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
e000: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
e010: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
e020: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
e030: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
e040: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
e050: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
e060: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
e070: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
e080: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
e090: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
e0a0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
e0b0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
e0c0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
e0d0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
e0e0: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
e0f0: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
e100: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
e110: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
e120: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
e130: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
e140: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
e150: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
e160: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
e170: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
e180: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
e190: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
e1a0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
e1b0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
e1c0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
e1d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
e1e0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
e1f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
e200: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
e210: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
e220: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
e230: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
e240: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
e250: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
e260: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
e270: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
e280: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
e290: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e2a0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
e2b0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
e2c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
e2d0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
e2e0: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
e2f0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e300: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
e310: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
e320: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
e330: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
e340: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
e350: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
e360: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
e370: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
e380: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
e390: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
e3a0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
e3b0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
e3c0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
e3d0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
e3e0: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
e3f0: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
e400: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
e410: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
e420: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
e430: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
e440: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
e450: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
e460: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
e470: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
e480: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
e490: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
e4a0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
e4b0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
e4c0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
e4d0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
e4e0: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
e4f0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
e500: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
e510: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
e520: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
e530: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
e540: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
e550: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
e560: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
e570: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
e580: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
e590: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
e5a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
e5b0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
e5c0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
e5d0: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
e5e0: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
e5f0: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
e600: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
e610: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
e620: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
e630: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
e640: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
e650: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
e660: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
e670: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
e680: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
e690: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
e6a0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
e6b0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
e6c0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
e6d0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
e6e0: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
e6f0: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
e700: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
e710: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
e720: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
e730: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
e740: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
e750: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
e760: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
e770: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
e780: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
e790: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
e7a0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
e7b0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
e7c0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
e7d0: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
e7e0: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
e7f0: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
e800: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
e810: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
e820: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
e830: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
e840: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
e850: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
e860: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
e870: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
e880: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
e890: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
e8a0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
e8b0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
e8c0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
e8d0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
e8e0: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
e8f0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
e900: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
e910: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
e920: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
e930: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
e940: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
e950: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
e960: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
e970: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
e980: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
e990: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
e9a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
e9b0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
e9c0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
e9d0: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
e9e0: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
e9f0: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
ea00: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
ea10: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
ea20: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
ea30: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
ea40: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
ea50: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
ea60: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
ea70: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
ea80: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b  en call..**.** [
ea90: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63  [sqlite3_vfs.xAc
eaa0: 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66  cess]].** ^The f
eab0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
eac0: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
ead0: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
eae0: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
eaf0: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
eb00: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
eb10: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
eb20: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
eb30: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
eb40: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
eb50: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
eb60: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
eb70: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
eb80: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
eb90: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
eba0: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
ebb0: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
ebc0: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
ebd0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  * ^SQLite will a
ebe0: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
ebf0: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
ec00: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
ec10: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
ec20: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
ec30: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
ec40: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
ec50: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
ec60: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
ec70: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
ec80: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
ec90: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
eca0: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
ecb0: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
ecc0: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
ecd0: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
ece0: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
ecf0: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
ed00: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
ed10: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
ed20: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
ed30: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
ed40: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
ed50: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
ed60: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
ed70: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
ed80: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
ed90: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
eda0: 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  , xCurrentTime()
edb0: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
edc0: 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74  meInt64().** int
edd0: 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20  erfaces are not 
ede0: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
edf0: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
ee00: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
ee10: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
ee20: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
ee30: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
ee40: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
ee50: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
ee60: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
ee70: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
ee80: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
ee90: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
eea0: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
eeb0: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
eec0: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
eed0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
eee0: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
eef0: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
ef00: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
ef10: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
ef20: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
ef30: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
ef40: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
ef50: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
ef60: 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54    ^The xCurrentT
ef70: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
ef80: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
ef90: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
efa0: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
efb0: 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20   and time as.** 
efc0: 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
efd0: 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20   value..** ^The 
efe0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
eff0: 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  4() method retur
f000: 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65  ns, as an intege
f010: 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a  r, the Julian.**
f020: 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74   Day Number mult
f030: 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30  iplied by 864000
f040: 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f  00 (the number o
f050: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69  f milliseconds i
f060: 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20  n .** a 24-hour 
f070: 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69  day).  .** ^SQLi
f080: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
f090: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
f0a0: 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65  4() method to ge
f0b0: 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  t the current.**
f0c0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69   date and time i
f0d0: 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73  f that method is
f0e0: 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69   available (if i
f0f0: 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20  Version is 2 or 
f100: 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20  .** greater and 
f110: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
f120: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
f130: 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20  ) and will fall 
f140: 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72  back.** to xCurr
f150: 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75  entTime() if xCu
f160: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
f170: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
f180: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74  .**.** ^The xSet
f190: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47  SystemCall(), xG
f1a0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
f1b0: 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43  and xNestSystemC
f1c0: 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73  all() interfaces
f1d0: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64  .** are not used
f1e0: 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63   by the SQLite c
f1f0: 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69  ore.  These opti
f200: 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  onal interfaces 
f210: 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
f220: 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f  by some VFSes to
f230: 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74   facilitate test
f240: 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63  ing of the VFS c
f250: 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69  ode. By overridi
f260: 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61  ng .** system ca
f270: 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f  lls with functio
f280: 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e  ns under its con
f290: 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f  trol, a test pro
f2a0: 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75  gram can.** simu
f2b0: 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20  late faults and 
f2c0: 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73  error conditions
f2d0: 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65   that would othe
f2e0: 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75  rwise be difficu
f2f0: 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69  lt.** or impossi
f300: 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20  ble to induce.  
f310: 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65  The set of syste
f320: 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e  m calls that can
f330: 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a   be overridden.*
f340: 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  * varies from on
f350: 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72  e VFS to another
f360: 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76  , and from one v
f370: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61  ersion of the sa
f380: 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a  me VFS to the.**
f390: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
f3a0: 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68  ions that use th
f3b0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
f3c0: 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20  ust be prepared 
f3d0: 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c  for any.** or al
f3e0: 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72  l of these inter
f3f0: 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c  faces to be NULL
f400: 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65   or for their be
f410: 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65  havior to change
f420: 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c  .** from one rel
f430: 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74  ease to the next
f440: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
f450: 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74  must not attempt
f460: 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e   to access.** an
f470: 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f  y of these metho
f480: 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69  ds if the iVersi
f490: 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73  on of the VFS is
f4a0: 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f   less than 3..*/
f4b0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
f4c0: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
f4d0: 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66  te3_vfs;.typedef
f4e0: 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
f4f0: 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69  syscall_ptr)(voi
f500: 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  d);.struct sqlit
f510: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
f520: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
f530: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
f540: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
f550: 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f  (currently 3) */
f560: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
f570: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
f580: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
f590: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
f5a0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
f5b0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
f5c0: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
f5d0: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
f5e0: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
f5f0: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
f600: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
f610: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
f620: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
f630: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
f640: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
f650: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
f660: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
f670: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
f680: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
f690: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
f6a0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
f6b0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f6c0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
f6d0: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
f6e0: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
f6f0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
f700: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
f710: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
f720: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
f730: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
f740: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
f750: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
f760: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
f770: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
f780: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
f790: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
f7a0: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
f7b0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
f7c0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
f7d0: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
f7e0: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
f7f0: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
f800: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
f810: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
f820: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
f830: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
f840: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
f850: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
f860: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
f870: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
f880: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
f890: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
f8a0: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
f8b0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
f8c0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
f8d0: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
f8e0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
f8f0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
f900: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
f910: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
f920: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
f930: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
f940: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
f950: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
f960: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
f970: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
f980: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
f990: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
f9a0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
f9b0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
f9c0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
f9d0: 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69  object.  ** defi
f9e0: 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74  nition.  Those t
f9f0: 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61  hat follow are a
fa00: 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20  dded in version 
fa10: 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a  2 or later.  */.
fa20: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
fa30: 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74  TimeInt64)(sqlit
fa40: 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33  e3_vfs*, sqlite3
fa50: 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20  _int64*);.  /*. 
fa60: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
fa70: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
fa80: 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66  sions 1 and 2 of
fa90: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
faa0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f  object..  ** Tho
fab0: 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72  se below are for
fac0: 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67   version 3 and g
fad0: 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69  reater..  */.  i
fae0: 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43  nt (*xSetSystemC
faf0: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
fb00: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
fb10: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79  Name, sqlite3_sy
fb20: 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71  scall_ptr);.  sq
fb30: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
fb40: 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61  r (*xGetSystemCa
fb50: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
fb60: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
fb70: 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68  ame);.  const ch
fb80: 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65  ar *(*xNextSyste
fb90: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
fba0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
fbb0: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20  *zName);.  /*.  
fbc0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
fbd0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
fbe0: 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33  ions 1 through 3
fbf0: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
fc00: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
fc10: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
fc20: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 75  e appended in fu
fc30: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  ture versions.  
fc40: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
fc50: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
fc60: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
fc70: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20  this happens. . 
fc80: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
fc90: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
fca0: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
fcb0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
fcc0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
fcd0: 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
fce0: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
fcf0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
fd00: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
fd10: 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
fd20: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
fd30: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
fd40: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
fd50: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
fd60: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
fd70: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a   looking for..**
fd80: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
fd90: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
fda0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
fdb0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
fdc0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
fdd0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68   exists..** With
fde0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
fdf0: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
fe00: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
fe10: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
fe20: 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f  he named directo
fe30: 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  ry is both reada
fe40: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
fe50: 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f  .** (in other wo
fe60: 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61  rds, if files ca
fe70: 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f  n be added, remo
fe80: 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64  ved, and renamed
fe90: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64   within.** the d
fea0: 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68  irectory)..** Th
feb0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
fec0: 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61  READWRITE consta
fed0: 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  nt is currently 
fee0: 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65  used only by the
fef0: 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  .** [temp_store_
ff00: 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
ff10: 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63  ], though this c
ff20: 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61  ould change in a
ff30: 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
ff40: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
ff50: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
ff60: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
ff70: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
ff80: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
ff90: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
ffa0: 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
ffb0: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e  _ACCESS_READ con
ffc0: 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72  stant is.** curr
ffd0: 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68  ently unused, th
ffe0: 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65  ough it might be
fff0: 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72   used in a futur
10000 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
10010 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
10020 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
10030 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
10040 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
10050 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20  SS_READWRITE 1  
10060 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47   /* Used by PRAG
10070 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  MA temp_store_di
10080 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69  rectory */.#defi
10090 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
100a0 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f  _READ      2   /
100b0 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  * Unused */../*.
100c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
100d0 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c  gs for the xShmL
100e0 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ock VFS method.*
100f0 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
10100 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  er constants def
10110 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20  ine the various 
10120 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f  locking operatio
10130 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79  ns.** allowed by
10140 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   the xShmLock me
10150 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  thod of [sqlite3
10160 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54  _io_methods].  T
10170 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
10180 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67  are the only leg
10190 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  al combinations 
101a0 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a  of flags to the.
101b0 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  ** xShmLock meth
101c0 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
101d0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
101e0 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
101f0 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
10200 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
10210 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
10220 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
10230 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
10240 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
10250 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
10260 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
10270 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
10280 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
10290 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  </ul>.**.** When
102a0 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20   unlocking, the 
102b0 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45  same SHARED or E
102c0 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75  XCLUSIVE flag mu
102d0 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61  st be supplied a
102e0 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f  s.** was given o
102f0 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
10300 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a  ing lock.  .**.*
10310 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
10320 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69  ethod can transi
10330 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c  tion between unl
10340 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44  ocked and SHARED
10350 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75   or.** between u
10360 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c  nlocked and EXCL
10370 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f  USIVE.  It canno
10380 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  t transition bet
10390 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61  ween SHARED.** a
103a0 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f  nd EXCLUSIVE..*/
103b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
103c0 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  SHM_UNLOCK      
103d0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
103e0 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20  E_SHM_LOCK      
103f0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
10400 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20  ITE_SHM_SHARED  
10410 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
10420 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
10430 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20  IVE    8../*.** 
10440 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75  CAPI3REF: Maximu
10450 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78  m xShmLock index
10460 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
10470 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73  ock method on [s
10480 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
10490 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65  s] may use value
104a0 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61  s.** between 0 a
104b0 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f  nd this upper bo
104c0 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73  und as its "offs
104d0 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  et" argument..**
104e0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
104f0 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65   will never atte
10500 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f  mpt to acquire o
10510 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c  r release a.** l
10520 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74  ock outside of t
10530 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65  his range.*/.#de
10540 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
10550 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a  NLOCK        8..
10560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10570 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
10580 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
10590 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
105a0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
105b0 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
105c0 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
105d0 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
105e0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
105f0 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
10600 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
10610 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
10620 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
10630 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10640 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
10650 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
10660 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
10670 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
10680 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
10690 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
106a0 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
106b0 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
106c0 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
106d0 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
106e0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
106f0 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
10700 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
10710 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
10720 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10730 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
10740 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
10750 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
10760 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
10770 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
10780 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
10790 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
107a0 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
107b0 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
107c0 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
107d0 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
107e0 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
107f0 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
10800 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
10810 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
10820 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
10830 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10840 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
10850 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
10860 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
10870 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
10880 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
10890 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
108a0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
108b0 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
108c0 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
108d0 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
108e0 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
108f0 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
10900 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
10910 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
10920 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
10930 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
10940 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
10950 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
10960 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
10970 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
10980 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
10990 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
109a0 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
109b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
109c0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
109d0 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
109e0 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
109f0 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
10a00 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
10a10 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
10a20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
10a30 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
10a40 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
10a50 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
10a60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
10a70 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
10a80 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
10a90 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
10aa0 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
10ab0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
10ac0 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
10ad0 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
10ae0 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
10af0 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
10b00 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
10b10 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
10b20 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
10b30 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
10b40 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
10b50 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
10b60 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
10b70 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
10b80 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
10b90 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
10ba0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
10bb0 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
10bc0 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
10bd0 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
10be0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
10bf0 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
10c00 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
10c10 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
10c20 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
10c30 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
10c40 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
10c50 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
10c60 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
10c70 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
10c80 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
10c90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
10ca0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10cb0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
10cc0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
10cd0 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
10ce0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
10cf0 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
10d00 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
10d10 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
10d20 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
10d30 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
10d40 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
10d50 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
10d60 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
10d70 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10d80 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
10d90 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
10da0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
10db0 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
10dc0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
10dd0 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
10de0 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
10df0 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
10e00 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
10e10 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
10e20 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
10e30 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
10e40 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
10e50 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
10e60 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
10e70 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
10e80 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
10e90 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
10ea0 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
10eb0 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
10ec0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10ed0 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
10ee0 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
10ef0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
10f00 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
10f10 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
10f20 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
10f30 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
10f40 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
10f50 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
10f60 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10f70 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
10f80 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
10f90 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
10fa0 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
10fb0 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
10fc0 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
10fd0 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
10fe0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
10ff0 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
11000 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
11010 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
11020 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
11030 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
11040 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
11050 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
11060 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
11070 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
11080 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11090 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
110a0 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
110b0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
110c0 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
110d0 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
110e0 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
110f0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
11100 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
11110 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
11120 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11130 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
11140 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
11150 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
11160 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
11170 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
11180 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
11190 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
111a0 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
111b0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
111c0 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
111d0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
111e0 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
111f0 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
11200 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
11210 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
11220 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
11230 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
11240 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
11250 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
11260 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
11270 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
11280 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
11290 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
112a0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
112b0 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
112c0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
112d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
112e0 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
112f0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
11300 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
11310 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
11320 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
11330 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
11340 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
11350 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
11360 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
11370 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
11380 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
11390 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
113a0 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
113b0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
113c0 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
113d0 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
113e0 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
113f0 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
11400 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
11410 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
11420 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
11430 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
11440 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
11450 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
11460 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
11470 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
11480 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
11490 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
114a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
114b0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
114c0 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
114d0 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
114e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
114f0 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
11500 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
11510 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
11520 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
11530 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
11540 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
11550 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
11560 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
11570 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
11580 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  re..*/.SQLITE_AP
11590 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e  I int sqlite3_in
115a0 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a  itialize(void);.
115b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
115c0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
115d0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
115e0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  I int sqlite3_os
115f0 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c  _init(void);.SQL
11600 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
11610 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
11620 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11630 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
11640 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
11650 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
11660 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
11670 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
11680 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
11690 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
116a0 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
116b0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
116c0 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
116d0 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
116e0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
116f0 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
11700 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
11710 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
11720 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
11730 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
11740 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
11750 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
11760 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
11770 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
11780 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
11790 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
117a0 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
117b0 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f   <b>The sqlite3_
117c0 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
117d0 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
117e0 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63  safe. The applic
117f0 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e  ation.** must en
11800 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
11810 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
11820 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
11830 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
11840 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
11850 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
11860 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a  unning.</b>.**.*
11870 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
11880 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
11890 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
118a0 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
118b0 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
118c0 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
118d0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
118e0 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
118f0 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
11900 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11910 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
11920 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
11930 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
11940 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11950 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
11960 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
11970 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
11980 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
11990 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
119a0 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
119b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
119c0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
119d0 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
119e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
119f0 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
11a00 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
11a10 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
11a20 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
11a30 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
11a40 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
11a50 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
11a60 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11a70 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
11a80 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
11a90 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
11aa0 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
11ab0 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
11ac0 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
11ad0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
11ae0 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
11af0 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
11b00 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11b10 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
11b20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
11b30 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
11b40 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11b50 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
11b60 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
11b70 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
11b80 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
11b90 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
11ba0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
11bb0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
11bc0 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
11bd0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
11be0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
11bf0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
11c00 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
11c10 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11c20 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
11c30 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  nnections.** MET
11c40 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
11c50 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
11c60 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
11c70 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
11c80 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
11c90 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
11ca0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
11cb0 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
11cc0 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
11cd0 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
11ce0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
11cf0 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
11d00 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
11d10 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
11d20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11d30 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
11d40 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11d50 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
11d60 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
11d70 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
11d80 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
11d90 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
11da0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
11db0 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
11dc0 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
11dd0 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
11de0 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
11df0 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
11e00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11e10 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
11e20 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
11e30 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
11e40 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
11e50 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
11e60 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
11e70 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
11e80 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
11e90 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
11ea0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
11eb0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
11ec0 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
11ed0 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  sful..*/.SQLITE_
11ee0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
11ef0 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
11f00 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
11f10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11f20 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
11f30 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
11f40 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
11f50 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
11f60 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
11f70 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
11f80 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
11f90 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
11fa0 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
11fb0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
11fc0 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
11fd0 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
11fe0 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
11ff0 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
12000 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
12010 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
12020 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
12030 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
12040 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
12050 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
12060 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
12070 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12080 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
12090 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
120a0 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
120b0 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
120c0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
120d0 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
120e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
120f0 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
12100 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
12110 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
12120 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
12130 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
12140 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
12150 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
12160 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
12170 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
12180 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
12190 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
121a0 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
121b0 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
121c0 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
121d0 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
121e0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
121f0 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
12200 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
12210 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
12220 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
12230 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
12240 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
12250 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
12260 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
12270 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
12280 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
12290 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
122a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
122b0 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
122c0 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
122d0 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
122e0 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
122f0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
12300 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
12310 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
12320 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
12330 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
12340 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
12350 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
12360 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
12370 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
12380 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
12390 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
123a0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
123b0 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
123c0 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
123d0 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
123e0 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
123f0 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
12400 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
12410 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
12420 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
12430 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
12440 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
12450 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
12460 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
12470 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
12480 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
12490 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
124a0 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
124b0 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
124c0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
124d0 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
124e0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
124f0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
12500 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
12510 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
12520 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
12530 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
12540 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
12550 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
12560 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
12570 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
12580 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
12590 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
125a0 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
125b0 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
125c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
125d0 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
125e0 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
125f0 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
12600 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
12610 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
12620 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
12630 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
12640 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
12650 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
12660 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
12670 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
12680 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
12690 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
126a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
126b0 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
126c0 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
126d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
126e0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
126f0 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
12700 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
12710 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
12720 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
12730 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
12740 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
12750 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
12760 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
12770 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
12780 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
12790 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f  y allocator.  Fo
127a0 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
127b0 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
127c0 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
127d0 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
127e0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
127f0 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
12800 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
12810 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
12820 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
12830 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
12840 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
12850 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
12860 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
12870 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
12880 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
12890 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
128a0 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
128b0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
128c0 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
128d0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
128e0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
128f0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
12900 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
12910 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
12920 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
12930 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
12940 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
12950 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
12960 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
12970 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
12980 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
12990 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
129a0 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
129b0 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
129c0 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
129d0 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
129e0 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
129f0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
12a00 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
12a10 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
12a20 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
12a30 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
12a40 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
12a50 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
12a60 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
12a70 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
12a80 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
12a90 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
12aa0 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
12ab0 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
12ac0 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
12ad0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
12ae0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
12af0 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
12b00 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
12b10 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
12b20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
12b30 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
12b40 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
12b50 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
12b60 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
12b70 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
12b80 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
12b90 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
12ba0 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
12bb0 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
12bc0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
12bd0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
12be0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12bf0 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
12c00 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
12c10 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
12c20 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
12c30 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
12c40 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
12c50 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
12c60 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
12c70 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
12c80 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
12c90 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
12ca0 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
12cb0 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
12cc0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
12cd0 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
12ce0 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
12cf0 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
12d00 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
12d10 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
12d20 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
12d30 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
12d40 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
12d50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
12d60 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
12d70 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
12d80 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
12d90 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
12da0 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
12db0 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
12dc0 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
12dd0 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
12de0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
12df0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
12e00 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
12e10 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
12e20 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
12e30 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
12e40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12e50 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
12e60 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
12e70 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
12e80 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
12e90 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
12ea0 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
12eb0 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
12ec0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12ed0 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
12ee0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
12ef0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
12f00 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
12f10 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
12f20 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
12f30 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12f40 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
12f50 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
12f60 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
12f70 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
12f80 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
12f90 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
12fa0 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
12fb0 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
12fc0 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
12fd0 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
12fe0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
12ff0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
13000 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
13010 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
13020 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
13030 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
13040 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
13050 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
13060 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
13070 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
13080 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13090 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
130a0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
130b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
130c0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
130d0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
130e0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
130f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
13100 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
13110 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
13120 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
13130 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
13140 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
13150 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
13160 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
13170 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
13180 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
13190 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
131a0 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
131b0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
131c0 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
131d0 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
131e0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
131f0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
13200 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
13210 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
13220 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
13230 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
13240 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
13250 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
13260 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
13270 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
13280 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
13290 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
132a0 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
132b0 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
132c0 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
132d0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
132e0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
132f0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
13300 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
13310 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
13320 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13330 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
13340 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
13350 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
13360 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
13370 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
13380 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
13390 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
133a0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
133b0 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
133c0 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
133d0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
133e0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
133f0 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
13400 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
13410 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
13420 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
13430 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
13440 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
13450 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
13460 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
13470 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
13480 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
13490 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
134a0 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
134b0 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
134c0 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
134d0 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
134e0 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
134f0 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
13500 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
13510 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
13520 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
13530 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
13540 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
13550 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
13560 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
13570 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
13580 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13590 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
135a0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
135b0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
135c0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
135d0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
135e0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
135f0 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
13600 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
13610 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
13620 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13630 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
13640 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
13650 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
13660 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
13670 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
13680 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
13690 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
136a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
136b0 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
136c0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
136d0 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
136e0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
136f0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
13700 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
13710 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
13720 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
13730 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
13740 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
13750 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
13760 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
13770 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
13780 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
13790 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
137a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
137b0 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
137c0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
137d0 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
137e0 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
137f0 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
13800 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13810 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
13820 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
13830 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
13840 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
13850 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
13860 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
13870 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
13880 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
13890 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
138a0 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
138b0 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
138c0 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
138d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
138e0 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
138f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13900 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
13910 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
13920 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
13930 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13940 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13950 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13960 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13970 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
13980 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13990 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
139a0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
139b0 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
139c0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
139d0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
139e0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
139f0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
13a00 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
13a10 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
13a20 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
13a30 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
13a40 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
13a50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13a60 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
13a70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13a80 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
13a90 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
13aa0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
13ab0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13ac0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13ad0 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
13ae0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
13af0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
13b00 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13b10 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
13b20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
13b30 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
13b40 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
13b50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13b60 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
13b70 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
13b80 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
13b90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
13ba0 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
13bb0 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
13bc0 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
13bd0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
13be0 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
13bf0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13c00 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
13c10 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
13c20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
13c30 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
13c40 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
13c50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13c60 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
13c70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13c80 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
13c90 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
13ca0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
13cb0 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
13cc0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13cd0 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
13ce0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
13cf0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
13d00 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13d10 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
13d20 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
13d30 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
13d40 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
13d50 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
13d60 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
13d70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13d80 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
13d90 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
13da0 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
13db0 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
13dc0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13dd0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
13de0 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
13df0 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
13e00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
13e10 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
13e20 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
13e30 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
13e40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13e50 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c  ITE_CONFIG_SMALL
13e60 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
13e70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c  LITE_CONFIG_SMAL
13e80 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  L_MALLOC</dt>.**
13e90 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
13ea0 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d  E_CONFIG_SMALL_M
13eb0 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
13ec0 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
13ed0 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20 69 6e  nt of.** type in
13ee0 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
13ef0 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  s a boolean, whi
13f00 63 68 20 69 66 20 74 72 75 65 20 70 72 6f 76 69  ch if true provi
13f10 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a 2a 2a  des a hint to.**
13f20 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
13f30 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c 61 72  should avoid lar
13f40 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ge memory alloca
13f50 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69 62 6c  tions if possibl
13f60 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  e..** SQLite wil
13f70 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69 66 20  l run faster if 
13f80 69 74 20 69 73 20 66 72 65 65 20 74 6f 20 6d 61  it is free to ma
13f90 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20  ke large memory 
13fa0 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a 2a 20  allocations,.** 
13fb0 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69 63 61  but some applica
13fc0 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65 66 65  tion might prefe
13fd0 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65 72 20  r to run slower 
13fe0 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f 72 0a  in exchange for.
13ff0 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 61 62  ** guarantees ab
14000 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61 67 6d  out memory fragm
14010 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 61 72  entation that ar
14020 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20 6c 61  e possible if la
14030 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  rge.** allocatio
14040 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64 2e 20  ns are avoided. 
14050 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f   This hint is no
14060 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a 20 3c  rmally off..** <
14070 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14080 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
14090 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
140a0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
140b0 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
140c0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
140d0 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74  IG_MEMSTATUS opt
140e0 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
140f0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
14100 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70  e int,.** interp
14110 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
14120 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
14130 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
14140 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a  e collection of.
14150 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
14160 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e  tion statistics.
14170 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
14180 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14190 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  tics are.** disa
141a0 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  bled, the follow
141b0 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
141c0 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
141d0 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
141e0 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
141f0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
14200 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
14210 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
14220 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
14230 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
14240 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
14250 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
14260 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
14270 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  us64()].**   </u
14280 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
14290 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
142a0 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
142b0 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
142c0 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
142d0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
142e0 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
142f0 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
14300 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
14310 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
14320 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
14330 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
14340 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
14350 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14360 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e  G_SCRATCH]] <dt>
14370 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14380 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
14390 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
143a0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74  NFIG_SCRATCH opt
143b0 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ion is no longer
143c0 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a   used..** </dd>.
143d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
143e0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
143f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14400 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
14410 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
14420 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
14430 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73  GECACHE option s
14440 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72  pecifies a memor
14450 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53  y pool.** that S
14460 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
14470 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  r the database p
14480 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74  age cache with t
14490 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a  he default page.
144a0 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
144b0 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  ntation.  .** Th
144c0 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
144d0 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d   option is a no-
144e0 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  op if an applica
144f0 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
14500 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
14510 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
14520 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ed using the [SQ
14530 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14540 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  HE2]..** ^There 
14550 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
14560 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
14570 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20  NFIG_PAGECACHE: 
14580 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  A pointer to.** 
14590 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d  8-byte aligned m
145a0 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68  emory (pMem), th
145b0 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
145c0 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28  age cache line (
145d0 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
145e0 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20  number of cache 
145f0 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  lines (N)..** Th
14600 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
14610 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
14620 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
14630 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
14640 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
14650 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
14660 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d   65536) plus som
14670 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f  e extra bytes fo
14680 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68  r each.** page h
14690 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d  eader.  ^The num
146a0 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74  ber of extra byt
146b0 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65  es needed by the
146c0 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20   page header.** 
146d0 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
146e0 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f  d using [SQLITE_
146f0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
14700 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20  RSZ]..** ^It is 
14710 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
14720 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
14730 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74  memory,.** for t
14740 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20  he sz parameter 
14750 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  to be larger tha
14760 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68  n necessary.  Th
14770 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65  e pMem.** argume
14780 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  nt must be eithe
14790 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
147a0 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   or a pointer to
147b0 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
147c0 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d  igned block of m
147d0 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73  emory of at leas
147e0 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74  t sz*N bytes, ot
147f0 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65  herwise.** subse
14800 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69  quent behavior i
14810 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
14820 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f  ^When pMem is no
14830 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
14840 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73  ill strive to us
14850 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
14860 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69  vided.** to sati
14870 73 66 79 20 70 61 67 65 20 63 61 63 68 65 20 6e  sfy page cache n
14880 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61  eeds, falling ba
14890 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  ck to [sqlite3_m
148a0 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61  alloc()] if.** a
148b0 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65   page cache line
148c0 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20   is larger than 
148d0 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 61  sz bytes or if a
148e0 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62  ll of the pMem b
148f0 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61  uffer.** is exha
14900 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d  usted..** ^If pM
14910 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e  em is NULL and N
14920 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   is non-zero, th
14930 65 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65  en each database
14940 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64   connection.** d
14950 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62  oes an initial b
14960 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ulk allocation f
14970 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  or page cache me
14980 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  mory.** from [sq
14990 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
149a0 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e  sufficient for N
149b0 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20   cache lines if 
149c0 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72  N is positive or
149d0 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62  .** of -1024*N b
149e0 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67  ytes if N is neg
149f0 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64  ative, . ^If add
14a00 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
14a10 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
14a20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
14a30 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
14a40 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a  y the initial.**
14a50 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
14a60 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  n SQLite goes to
14a70 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14a80 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66  ()] separately f
14a90 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74  or each.** addit
14aa0 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65  ional cache line
14ab0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
14ac0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14ad0 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AP]] <dt>SQLITE_
14ae0 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
14af0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
14b00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14b10 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
14b20 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
14b30 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61  y buffer .** tha
14b40 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
14b50 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
14b60 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
14b70 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
14b80 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  .** beyond those
14b90 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79   provided for by
14ba0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
14bb0 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e  PAGECACHE]..** ^
14bc0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14bd0 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73  G_HEAP option is
14be0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
14bf0 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
14c00 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69  piled.** with ei
14c10 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
14c20 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20  BLE_MEMSYS3] or 
14c30 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
14c40 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75  EMSYS5] and retu
14c50 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rns.** [SQLITE_E
14c60 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64  RROR] if invoked
14c70 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e   otherwise..** ^
14c80 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
14c90 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
14ca0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a  ITE_CONFIG_HEAP:
14cb0 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  .** An 8-byte al
14cc0 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
14cd0 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
14ce0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
14cf0 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
14d00 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
14d10 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
14d20 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
14d30 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
14d40 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
14d50 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
14d60 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
14d70 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
14d80 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
14d90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
14da0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
14db0 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
14dc0 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
14dd0 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
14de0 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
14df0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
14e00 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
14e10 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
14e20 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  t NULL then the 
14e30 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
14e40 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
14e50 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
14e60 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
14e70 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
14e80 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
14e90 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
14ea0 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
14eb0 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
14ec0 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
14ed0 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
14ee0 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
14ef0 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
14f00 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
14f10 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d  ed..** The minim
14f20 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
14f30 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20  ze is capped at 
14f40 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c  2**12. Reasonabl
14f50 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20  e values.** for 
14f60 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
14f70 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20  cation size are 
14f80 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a  2**5 through 2**
14f90 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  8.</dd>.**.** [[
14fa0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14fb0 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
14fc0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
14fd0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14fe0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14ff0 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65  UTEX option take
15000 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15010 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a  ent which is a.*
15020 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
15030 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
15040 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
15050 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
15060 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
15070 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c 74  nt specifies alt
15080 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
15090 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
150a0 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20  s to be used.** 
150b0 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74  in place the mut
150c0 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
150d0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
150e0 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
150f0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
15100 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
15110 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
15120 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
15130 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
15140 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
15150 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
15160 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
15170 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
15180 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
15190 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
151a0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
151b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
151c0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
151d0 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
151e0 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
151f0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
15200 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
15210 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
15220 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
15230 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
15240 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
15250 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
15260 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
15270 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
15280 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15290 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
152a0 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
152b0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
152c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
152d0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
152e0 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e  _GETMUTEX option
152f0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15300 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
15310 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
15320 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
15330 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
15340 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
15350 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
15360 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
15370 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
15380 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
15390 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
153a0 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
153b0 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
153c0 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
153d0 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
153e0 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
153f0 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
15400 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
15410 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
15420 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
15430 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
15440 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
15450 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
15460 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
15470 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
15480 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
15490 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
154a0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
154b0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
154c0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
154d0 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
154e0 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
154f0 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
15500 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
15510 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
15520 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
15530 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
15540 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15550 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
15560 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
15570 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
15580 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
15590 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
155a0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
155b0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
155c0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
155d0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
155e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
155f0 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20  OOKASIDE option 
15600 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
15610 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
15620 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  ne.** the defaul
15630 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73  t size of lookas
15640 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61  ide memory on ea
15650 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ch [database con
15660 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65  nection]..** The
15670 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15680 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
15690 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
156a0 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
156b0 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
156c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
156d0 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
156e0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
156f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
15700 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ^(SQLITE_CONFIG_
15710 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74  LOOKASIDE.** set
15720 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74  s the <i>default
15730 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
15740 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
15750 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
15760 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74  IDE].** option t
15770 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
15780 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75  nfig()] can be u
15790 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
157a0 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63  e lookaside.** c
157b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20  onfiguration on 
157c0 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65  individual conne
157d0 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a  ctions.)^ </dd>.
157e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
157f0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20  ONFIG_PCACHE2]] 
15800 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15810 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  G_PCACHE2</dt>.*
15820 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
15830 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
15840 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  E2 option takes 
15850 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
15860 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
15870 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
15880 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
15890 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
158a0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
158b0 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69  ecifies.** the i
158c0 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 75  nterface to a cu
158d0 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
158e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
158f0 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b  ^.** ^SQLite mak
15900 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
15910 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
15920 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
15930 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  t.</dd>.**.** [[
15940 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15950 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
15960 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15970 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
15980 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
15990 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
159a0 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
159b0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
159c0 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
159d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
159e0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
159f0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
15a00 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
15a10 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e  of.** the curren
15a20 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
15a30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
15a40 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
15a50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15a60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
15a70 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15a80 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
15a90 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
15aa0 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
15ab0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  n is used to con
15ac0 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74  figure the SQLit
15ad0 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72  e.** global [err
15ae0 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68  or log]..** (^Th
15af0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15b00 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
15b10 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
15b20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
15b30 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
15b40 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
15b50 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
15b60 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
15b70 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
15b80 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
15b90 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
15ba0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
15bb0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
15bc0 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
15bd0 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
15be0 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
15bf0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
15c00 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
15c10 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
15c20 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
15c30 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
15c40 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
15c50 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
15c60 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
15c70 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
15c80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15c90 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
15ca0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
15cb0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
15cc0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
15cd0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
15ce0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
15cf0 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
15d00 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
15d10 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
15d20 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
15d30 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
15d40 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
15d50 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15d60 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
15d70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
15d80 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
15d90 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
15da0 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
15db0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
15dc0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
15dd0 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
15de0 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
15df0 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
15e00 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
15e10 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
15e20 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
15e30 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
15e40 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
15e50 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
15e60 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
15e70 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
15e80 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
15e90 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
15ea0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
15eb0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
15ec0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
15ed0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
15ee0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
15ef0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
15f00 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
15f10 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
15f20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
15f30 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15f40 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
15f50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15f60 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65  URI.** <dd>^(The
15f70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
15f80 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  RI option takes 
15f90 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
15fa0 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a  t of type int..*
15fb0 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  * If non-zero, t
15fc0 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
15fd0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
15fe0 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
15ff0 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a  ameter is zero,.
16000 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  ** then URI hand
16010 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
16020 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66   disabled.)^ ^If
16030 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
16040 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61   globally.** ena
16050 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61  bled, all filena
16060 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73  mes passed to [s
16070 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
16080 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
16090 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
160a0 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a  _open16()] or.**
160b0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
160c0 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63  rt of [ATTACH] c
160d0 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65  ommands are inte
160e0 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c  rpreted as URIs,
160f0 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
16100 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
16110 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
16120 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73  N_URI] flag is s
16130 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  et when the data
16140 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
16150 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49  on is opened. ^I
16160 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
16170 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
16180 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
16190 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
161a0 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
161b0 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
161c0 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
161d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
161e0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
161f0 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c  d. ^(By default,
16200 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
16210 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73   globally.** dis
16220 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75  abled. The defau
16230 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20  lt value may be 
16240 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69  changed by compi
16250 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a  ling with the.**
16260 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
16270 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  ] symbol defined
16280 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
16290 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
162a0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20  NG_INDEX_SCAN]] 
162b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
162c0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
162d0 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68  _SCAN.** <dd>^Th
162e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
162f0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
16300 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  CAN option takes
16310 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
16320 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68  r.** argument wh
16330 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
16340 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20  ed as a boolean 
16350 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
16360 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a  le or disable.**
16370 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
16380 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
16390 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
163a0 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
163b0 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68  ptimizer..** ^Th
163c0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
163d0 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
163e0 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
163f0 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
16400 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
16410 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
16420 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
16430 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
16440 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
16450 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
16460 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
16470 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
16480 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
16490 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
164a0 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
164b0 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
164c0 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
164d0 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
164e0 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
164f0 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69   when the optimi
16500 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  zation is enable
16510 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68  d.  Providing th
16520 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20  e ability to.** 
16530 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69  disable the opti
16540 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  mization allows 
16550 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79  the older, buggy
16560 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
16570 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
16580 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e  hout change even
16590 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73   with newer vers
165a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
165b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
165c0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b  ONFIG_PCACHE]] [
165d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
165e0 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64  ETPCACHE]].** <d
165f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16600 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54  PCACHE and SQLIT
16610 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16620 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65  HE.** <dd> These
16630 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73   options are obs
16640 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64  olete and should
16650 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
16660 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65  new code..** The
16670 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  y are retained f
16680 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
16690 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61  patibility but a
166a0 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a  re now no-ops..*
166b0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
166c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
166d0 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  LLOG]].** <dt>SQ
166e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
166f0 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  OG.** <dd>This o
16700 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
16710 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74  ailable if sqlit
16720 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
16730 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
16740 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d  E_ENABLE_SQLLOG]
16750 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
16760 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68  acro defined. Th
16770 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16780 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20   should.** be a 
16790 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
167a0 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f  ction of type vo
167b0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
167c0 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  te3*,const char*
167d0 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73  , int)..** The s
167e0 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  econd should be 
167f0 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e  of type (void*).
16800 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
16810 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20   invoked by the 
16820 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68  library.** in th
16830 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72  ree separate cir
16840 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e  cumstances, iden
16850 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61  tified by the va
16860 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
16870 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
16880 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f  meter. If the fo
16890 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
168a0 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61  s 0, then the da
168b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
168c0 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  n.** passed as t
168d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
168e0 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  nt has just been
168f0 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69   opened. The thi
16900 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70  rd argument.** p
16910 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
16920 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  r containing the
16930 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69   name of the mai
16940 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
16950 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
16960 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31  h parameter is 1
16970 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73  , then the SQL s
16980 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68  tatement that th
16990 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
169a0 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68  r.** points to h
169b0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65  as just been exe
169c0 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68  cuted. Or, if th
169d0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
169e0 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a  er is 2, then.**
169f0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
16a00 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20  being passed as 
16a10 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
16a20 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c  eter is being cl
16a30 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69  osed. The.** thi
16a40 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
16a50 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74  passed NULL In t
16a60 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78  his case.  An ex
16a70 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74  ample of using t
16a80 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  his.** configura
16a90 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20  tion option can 
16aa0 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22  be seen in the "
16ab0 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73  test_sqllog.c" s
16ac0 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a  ource file in.**
16ad0 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53   the canonical S
16ae0 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65  QLite source tre
16af0 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  e.</dd>.**.** [[
16b00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
16b10 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  AP_SIZE]].** <dt
16b20 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
16b30 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  MAP_SIZE.** <dd>
16b40 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  ^SQLITE_CONFIG_M
16b50 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74  MAP_SIZE takes t
16b60 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  wo 64-bit intege
16b70 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  r (sqlite3_int64
16b80 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  ) values.** that
16b90 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74   are the default
16ba0 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
16bb0 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65   (the default se
16bc0 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52  tting for.** [PR
16bd0 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29  AGMA mmap_size])
16be0 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
16bf0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
16c00 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68  ze limit..** ^Th
16c10 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
16c20 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  g can be overrid
16c30 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61  den by each data
16c40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16c50 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20  using.** either 
16c60 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  the [PRAGMA mmap
16c70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20  _size] command, 
16c80 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a  or by using the.
16c90 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
16ca0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
16cb0 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65   control.  ^(The
16cc0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
16cd0 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69   mmap size.** wi
16ce0 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74  ll be silently t
16cf0 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65  runcated if nece
16d00 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 74  ssary so that it
16d10 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64   does not exceed
16d20 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d   the.** compile-
16d30 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61  time maximum mma
16d40 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68  p size set by th
16d50 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  e.** [SQLITE_MAX
16d60 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70  _MMAP_SIZE] comp
16d70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
16d80 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72  )^.** ^If either
16d90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
16da0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61  s option is nega
16db0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20  tive, then that 
16dc0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63  argument is.** c
16dd0 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f  hanged to its co
16de0 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75  mpile-time defau
16df0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  lt..**.** [[SQLI
16e00 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
16e10 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  HEAPSIZE]].** <d
16e20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16e30 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a  WIN32_HEAPSIZE.*
16e40 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
16e50 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
16e60 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69  EAPSIZE option i
16e70 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
16e80 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a   if SQLite is.**
16e90 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69   compiled for Wi
16ea0 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b  ndows with the [
16eb0 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c  SQLITE_WIN32_MAL
16ec0 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOC] pre-process
16ed0 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69  or macro.** defi
16ee0 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e  ned. ^SQLITE_CON
16ef0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
16f00 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69  ZE takes a 32-bi
16f10 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
16f20 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74  er value.** that
16f30 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d   specifies the m
16f40 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74  aximum size of t
16f50 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e  he created heap.
16f60 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16f70 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
16f80 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  RSZ]].** <dt>SQL
16f90 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16fa0 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  E_HDRSZ.** <dd>^
16fb0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16fc0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f  G_PCACHE_HDRSZ o
16fd0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
16fe0 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
16ff0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
17000 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
17010 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  er and writes in
17020 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
17030 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
17040 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72  tra.** bytes per
17050 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66   page required f
17060 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20  or each page in 
17070 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
17080 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
17090 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72  e amount of extr
170a0 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64  a space required
170b0 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65   can change depe
170c0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d  nding on the com
170d0 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74  piler,.** target
170e0 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53   platform, and S
170f0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a  QLite version..*
17100 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17110 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20  NFIG_PMASZ]].** 
17120 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17130 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  G_PMASZ.** <dd>^
17140 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
17150 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74  G_PMASZ option t
17160 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61  akes a single pa
17170 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
17180 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
17190 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 73  integer and sets
171a0 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d   the "Minimum PM
171b0 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20  A Size" for the 
171c0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a  multithreaded.**
171d0 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20   sorter to that 
171e0 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 65  integer.  The de
171f0 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d  fault minimum PM
17200 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79  A Size is set by
17210 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
17220 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f  SORTER_PMASZ] co
17230 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
17240 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 20  n.  New threads 
17250 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20  are launched.** 
17260 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72  to help with sor
17270 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65  t operations whe
17280 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  n multithreaded 
17290 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e  sorting.** is en
172a0 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65  abled (using the
172b0 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 73   [PRAGMA threads
172c0 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74  ] command) and t
172d0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e  he amount of con
172e0 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f  tent.** to be so
172f0 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68 65  rted exceeds the
17300 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73   page size times
17310 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20   the minimum of 
17320 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63  the.** [PRAGMA c
17330 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69  ache_size] setti
17340 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75  ng and this valu
17350 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
17360 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
17370 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74  L_SPILL]].** <dt
17380 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
17390 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a  TMTJRNL_SPILL.**
173a0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
173b0 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c  _CONFIG_STMTJRNL
173c0 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61  _SPILL option ta
173d0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
173e0 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
173f0 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61  becomes the [sta
17400 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20  tement journal] 
17410 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68  spill-to-disk th
17420 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53  reshold.  .** [S
17430 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
17440 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d  s] are held in m
17450 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69  emory until thei
17460 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73  r size (in bytes
17470 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69  ).** exceeds thi
17480 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20  s threshold, at 
17490 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79  which point they
174a0 20 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20   are written to 
174b0 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74  disk..** Or if t
174c0 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20  he threshold is 
174d0 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f  -1, statement jo
174e0 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79  urnals are alway
174f0 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73  s held.** exclus
17500 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e  ively in memory.
17510 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73  .** Since many s
17520 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
17530 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c  s never become l
17540 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68  arge, setting th
17550 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73  e spill.** thres
17560 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20  hold to a value 
17570 73 75 63 68 20 61 73 20 36 34 4b 69 42 20 63 61  such as 64KiB ca
17580 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75 63 65  n greatly reduce
17590 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a   the amount of.*
175a0 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74  * I/O required t
175b0 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d  o support statem
175c0 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  ent rollback..**
175d0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
175e0 75 65 20 66 6f 72 20 74 68 69 73 20 73 65 74 74  ue for this sett
175f0 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65  ing is controlle
17600 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  d by the.** [SQL
17610 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  ITE_STMTJRNL_SPI
17620 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  LL] compile-time
17630 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c   option..** </dl
17640 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
17650 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
17660 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
17670 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
17680 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
17690 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
176a0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
176b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
176c0 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
176d0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
176e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
176f0 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
17700 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
17710 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
17720 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17730 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
17740 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
17750 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
17760 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17770 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
17780 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20  6  /* No longer 
17790 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
177a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
177b0 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
177c0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
177d0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
177e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
177f0 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
17800 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
17810 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
17820 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17830 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
17840 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
17850 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
17860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
17870 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
17880 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
17890 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
178a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
178b0 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
178c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
178d0 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
178e0 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
178f0 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
17900 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
17910 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
17920 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17930 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17940 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
17950 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
17960 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17970 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
17980 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
17990 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
179a0 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
179b0 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
179c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
179d0 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
179e0 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
179f0 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
17a00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
17a10 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
17a20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
17a30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17a40 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
17a50 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
17a60 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
17a70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17a80 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
17a90 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
17aa0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
17ab0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17ac0 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
17ad0 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
17ae0 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
17af0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17b00 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
17b10 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
17b20 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
17b30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
17b40 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
17b50 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
17b60 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
17b70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17b80 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
17b90 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
17ba0 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
17bb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17bc0 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
17bd0 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20  Z        24  /* 
17be0 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66  int *psz */.#def
17bf0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17c00 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20  G_PMASZ         
17c10 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73        25  /* uns
17c20 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20  igned int szPma 
17c30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17c40 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
17c50 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20  L_SPILL      26 
17c60 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
17c70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17c80 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c  CONFIG_SMALL_MAL
17c90 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20 20 2f  LOC        27  /
17ca0 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 0a 2f 2a  * boolean */../*
17cb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
17cc0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
17cd0 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
17ce0 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
17cf0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
17d00 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
17d10 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
17d20 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
17d30 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
17d40 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
17d50 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
17d60 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
17d70 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
17d80 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
17d90 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17da0 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
17db0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
17dc0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
17dd0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
17de0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17df0 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
17e00 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
17e10 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
17e20 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
17e30 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
17e40 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17e50 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
17e60 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
17e70 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
17e80 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
17e90 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
17ea0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
17eb0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
17ec0 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
17ed0 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
17ee0 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
17ef0 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
17f00 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
17f10 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
17f20 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
17f30 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
17f40 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
17f50 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
17f60 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
17f70 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
17f80 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
17f90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
17fa0 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
17fb0 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
17fc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
17fd0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
17fe0 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
17ff0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
18000 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
18010 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
18020 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
18030 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
18040 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
18050 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
18060 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
18070 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
18080 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
18090 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
180a0 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
180b0 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
180c0 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
180d0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
180e0 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
180f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
18100 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
18110 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
18120 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
18130 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
18140 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
18150 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
18160 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
18170 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
18180 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
18190 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
181a0 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
181b0 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
181c0 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
181d0 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
181e0 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
181f0 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
18200 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
18210 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
18220 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
18230 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18240 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
18250 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
18260 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
18270 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
18280 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
18290 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
182a0 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
182b0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
182c0 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
182d0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
182e0 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
182f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18300 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
18310 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
18320 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
18330 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
18340 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
18350 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
18360 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
18370 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
18380 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
18390 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
183a0 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
183b0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
183c0 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
183d0 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
183e0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
183f0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
18400 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
18410 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
18420 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
18430 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
18440 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
18450 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
18460 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
18470 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
18480 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18490 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
184a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
184b0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
184c0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
184d0 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
184e0 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
184f0 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
18500 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
18510 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
18520 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
18530 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
18540 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
18550 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
18560 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
18570 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
18580 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
18590 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
185a0 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
185b0 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
185c0 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
185d0 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
185e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
185f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
18600 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
18610 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
18620 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
18630 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
18640 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
18650 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
18660 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
18670 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18680 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
18690 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
186a0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
186b0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
186c0 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
186d0 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
186e0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
186f0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18700 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
18710 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
18720 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
18730 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
18740 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
18750 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
18760 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
18770 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18780 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
18790 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
187a0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
187b0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
187c0 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
187d0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
187e0 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
187f0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
18800 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
18810 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
18820 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18830 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
18840 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
18850 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
18860 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
18870 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
18880 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
18890 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
188a0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
188b0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
188c0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
188d0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
188e0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
188f0 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
18900 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
18910 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
18920 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
18930 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18940 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
18950 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a  OKENIZER</dt>.**
18960 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
18970 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
18980 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
18990 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74  the two-argument
189a0 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  .** version of t
189b0 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  he [fts3_tokeniz
189c0 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77  er()] function w
189d0 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20  hich is part of 
189e0 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75  the.** [FTS3] fu
189f0 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65  ll-text search e
18a00 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e  ngine extension.
18a10 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18a20 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18a30 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18a40 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
18a50 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
18a60 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
18a70 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b  disable fts3_tok
18a80 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70  enizer() or.** p
18a90 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
18aa0 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  e fts3_tokenizer
18ab0 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  () or negative t
18ac0 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
18ad0 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ing.** unchanged
18ae0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
18af0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
18b00 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
18b10 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
18b20 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
18b30 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
18b40 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f   whether fts3_to
18b50 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62  kenizer is disab
18b60 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
18b70 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
18b80 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
18b90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
18ba0 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
18bb0 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
18bc0 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74  case the new set
18bd0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
18be0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
18bf0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18c00 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18c10 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e  E_LOAD_EXTENSION
18c20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
18c30 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
18c40 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
18c50 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c  disable the [sql
18c60 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
18c70 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ion()].** interf
18c80 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c  ace independentl
18c90 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65  y of the [load_e
18ca0 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20  xtension()] SQL 
18cb0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  function..** The
18cc0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
18cd0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
18ce0 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f  )] API enables o
18cf0 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20  r disables both 
18d00 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71  the.** C-API [sq
18d10 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
18d20 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20  sion()] and the 
18d30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f  SQL function [lo
18d40 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e  ad_extension()].
18d50 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18d60 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18d70 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18d80 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20   When the first 
18d90 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
18da0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c   interface is 1,
18db0 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43   then only the C
18dc0 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c  -API is.** enabl
18dd0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  ed and the SQL f
18de0 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20  unction remains 
18df0 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68  disabled.  If th
18e00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18e10 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65   to.** this inte
18e20 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e  rface is 0, then
18e30 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20   both the C-API 
18e40 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
18e50 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65  tion are disable
18e60 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72  d..** If the fir
18e70 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d  st argument is -
18e80 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67  1, then no chang
18e90 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73  es are made to s
18ea0 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74  tate of either t
18eb0 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74  he.** C-API or t
18ec0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
18ed0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
18ee0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
18ef0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
18f00 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
18f10 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
18f20 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
18f30 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33  whether [sqlite3
18f40 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
18f50 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
18f60 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
18f70 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67  nabled following
18f80 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
18f90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18fa0 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55  r may.** be a NU
18fb0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77  LL pointer, in w
18fc0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65  hich case the ne
18fd0 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  w setting is not
18fe0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a   reported back..
18ff0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
19000 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
19010 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64  IG_MAINDBNAME</d
19020 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
19030 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
19040 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61  to change the na
19050 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22  me of the "main"
19060 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68   database.** sch
19070 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20  ema.  ^The sole 
19080 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
19090 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74  inter to a const
190a0 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a  ant UTF8 string.
190b0 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
190c0 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68  come the new sch
190d0 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63  ema name in plac
190e0 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53  e of "main".  ^S
190f0 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  QLite.** does no
19100 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  t make a copy of
19110 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63   the new main sc
19120 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67  hema name string
19130 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61  , so the applica
19140 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
19150 75 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67  ure that the arg
19160 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74  ument passed int
19170 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20  o this DBCONFIG 
19180 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e  option is unchan
19190 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74  ged.** until aft
191a0 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  er the database 
191b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
191c0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
191d0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
191e0 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e  ONFIG_NO_CKPT_ON
191f0 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  _CLOSE</dt>.** <
19200 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65  dd> Usually, whe
19210 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20  n a database in 
19220 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73  wal mode is clos
19230 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66  ed or detached f
19240 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61  rom a .** databa
19250 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74  se handle, SQLit
19260 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73  e checks if this
19270 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20   will mean that 
19280 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f  there are now no
19290 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   .** connections
192a0 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64   at all to the d
192b0 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20  atabase. If so, 
192c0 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68  it performs a ch
192d0 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65  eckpoint .** ope
192e0 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c  ration before cl
192f0 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63  osing the connec
19300 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f  tion. This optio
19310 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  n may be used to
19320 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69  .** override thi
19330 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65  s behaviour. The
19340 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
19350 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20   passed to this 
19360 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  operation.** is 
19370 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e  an integer - non
19380 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65  -zero to disable
19390 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d   checkpoints-on-
193a0 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28  close, or zero (
193b0 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20  the.** default) 
193c0 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20  to enable them. 
193d0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
193e0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
193f0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  r to an integer.
19400 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73  ** into which is
19410 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
19420 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
19430 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d  her checkpoints-
19440 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65  on-close.** have
19450 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d   been disabled -
19460 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e   0 if they are n
19470 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69  ot disabled, 1 i
19480 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c  f they are..** <
19490 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
194a0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
194b0 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a  NABLE_QPSG</dt>.
194c0 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c  ** <dd>^(The SQL
194d0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
194e0 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20  BLE_QPSG option 
194f0 61 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61  activates or dea
19500 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20  ctivates.** the 
19510 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 73  [query planner s
19520 74 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e 74  tability guarant
19530 65 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68 65  ee] (QPSG).  Whe
19540 6e 20 74 68 65 20 51 50 53 47 20 69 73 20 61 63  n the QPSG is ac
19550 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c  tive,.** a singl
19560 65 20 53 51 4c 20 71 75 65 72 79 20 73 74 61 74  e SQL query stat
19570 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79  ement will alway
19580 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 61  s use the same a
19590 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64 6c  lgorithm regardl
195a0 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73  ess.** of values
195b0 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
195c0 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51 50  eters].)^ The QP
195d0 53 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d 65  SG disables some
195e0 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61 74   query optimizat
195f0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f  ions.** that loo
19600 6b 20 61 74 20 74 68 65 20 76 61 6c 75 65 73 20  k at the values 
19610 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  of bound paramet
19620 65 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20 6d  ers, which can m
19630 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65 73  ake some queries
19640 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75 74  .** slower.  But
19650 20 74 68 65 20 51 50 53 47 20 68 61 73 20 74 68   the QPSG has th
19660 65 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20 6d  e advantage of m
19670 6f 72 65 20 70 72 65 64 69 63 74 61 62 6c 65 20  ore predictable 
19680 62 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68 0a  behavior.  With.
19690 2a 2a 20 74 68 65 20 51 50 53 47 20 61 63 74 69  ** the QPSG acti
196a0 76 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ve, SQLite will 
196b0 61 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73  always use the s
196c0 61 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20 69  ame query plan i
196d0 6e 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a 2a  n the field as.*
196e0 2a 20 77 61 73 20 75 73 65 64 20 64 75 72 69 6e  * was used durin
196f0 67 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68 65  g testing in the
19700 20 6c 61 62 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a   lab..** </dd>.*
19710 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
19720 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
19730 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45  ONFIG_MAINDBNAME
19740 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30 30              1000
19750 20 2f 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a 20   /* const char* 
19760 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19770 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
19780 53 49 44 45 20 20 20 20 20 20 20 20 20 20 20 20  SIDE            
19790 20 31 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69   1001 /* void* i
197a0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
197b0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
197c0 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20  G_ENABLE_FKEY   
197d0 20 20 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20          1002 /* 
197e0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
197f0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
19800 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
19810 45 52 20 20 20 20 20 20 20 20 31 30 30 33 20 2f  ER        1003 /
19820 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
19830 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
19840 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53  ONFIG_ENABLE_FTS
19850 33 5f 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34  3_TOKENIZER 1004
19860 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
19870 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19880 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c  BCONFIG_ENABLE_L
19890 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30  OAD_EXTENSION 10
198a0 30 35 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  05 /* int int* *
198b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
198c0 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50  _DBCONFIG_NO_CKP
198d0 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20  T_ON_CLOSE      
198e0 31 30 30 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1006 /* int int*
198f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19900 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19910 4c 45 5f 51 50 53 47 20 20 20 20 20 20 20 20 20  LE_QPSG         
19920 20 20 31 30 30 37 20 2f 2a 20 69 6e 74 20 69 6e    1007 /* int in
19930 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
19940 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
19950 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
19960 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
19970 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
19980 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
19990 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
199a0 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
199b0 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
199c0 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
199d0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
199e0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
199f0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
19a00 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
19a10 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
19a20 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
19a30 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
19a40 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
19a50 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
19a60 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
19a70 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
19a80 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
19a90 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
19aa0 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
19ab0 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48  rt Rowid.** METH
19ac0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
19ad0 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
19ae0 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62   most SQLite tab
19af0 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20  les (except for 
19b00 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
19b10 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61  tables).** has a
19b20 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
19b30 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
19b40 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
19b50 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
19b60 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
19b70 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
19b80 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
19b90 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
19ba0 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
19bb0 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
19bc0 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
19bd0 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
19be0 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
19bf0 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
19c00 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
19c10 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
19c20 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
19c30 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
19c40 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
19c50 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
19c60 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
19c70 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  owid..**.** ^The
19c80 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
19c90 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e  sert_rowid(D) in
19ca0 74 65 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20  terface usually 
19cb0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
19cc0 69 64 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f  id] of.** the mo
19cd0 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
19ce0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
19cf0 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65  to a rowid table
19d00 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
19d10 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61  le].** on databa
19d20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
19d30 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b   ^Inserts into [
19d40 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
19d50 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ables are not.**
19d60 20 72 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e   recorded. ^If n
19d70 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
19d80 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69  SERT]s into rowi
19d90 64 20 74 61 62 6c 65 73 20 68 61 76 65 20 65 76  d tables have ev
19da0 65 72 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20  er occurred .** 
19db0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
19dc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68  connection D, th
19dd0 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  en sqlite3_last_
19de0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
19df0 72 65 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f  returns .** zero
19e00 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20  ..**.** As well 
19e10 61 73 20 62 65 69 6e 67 20 73 65 74 20 61 75 74  as being set aut
19e20 6f 6d 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f  omatically as ro
19e30 77 73 20 61 72 65 20 69 6e 73 65 72 74 65 64 20  ws are inserted 
19e40 69 6e 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a  into database.**
19e50 20 74 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c   tables, the val
19e60 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
19e70 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
19e80 20 62 65 20 73 65 74 20 65 78 70 6c 69 63 69 74   be set explicit
19e90 6c 79 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ly by.** [sqlite
19ea0 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
19eb0 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a  t_rowid()].**.**
19ec0 20 53 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61   Some virtual ta
19ed0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
19ee0 6f 6e 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72  ons may INSERT r
19ef0 6f 77 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74  ows into rowid t
19f00 61 62 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74  ables as.** part
19f10 20 6f 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61   of committing a
19f20 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e   transaction (e.
19f30 67 2e 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  g. to flush data
19f40 20 61 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20   accumulated in 
19f50 6d 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73  memory.** to dis
19f60 6b 29 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65  k). In this case
19f70 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
19f80 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
19f90 6f 6e 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f  on return the ro
19fa0 77 69 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  wid.** associate
19fb0 64 20 77 69 74 68 20 74 68 65 73 65 20 69 6e 74  d with these int
19fc0 65 72 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65  ernal INSERT ope
19fd0 72 61 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c  rations, which l
19fe0 65 61 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e  eads to .** unin
19ff0 74 75 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e  tuitive results.
1a000 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
1a010 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
1a020 68 61 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20  hat do write to 
1a030 72 6f 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20  rowid.** tables 
1a040 69 6e 20 74 68 69 73 20 77 61 79 20 63 61 6e 20  in this way can 
1a050 61 76 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c  avoid this probl
1a060 65 6d 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20  em by restoring 
1a070 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a  the original .**
1a080 20 72 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69   rowid value usi
1a090 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ng [sqlite3_set_
1a0a0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1a0b0 64 28 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75  d()] before retu
1a0c0 72 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f  rning .** contro
1a0d0 6c 20 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a  l to the user..*
1a0e0 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
1a0f0 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
1a100 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 74 68  hin a trigger th
1a110 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
1a120 77 69 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20  will .** return 
1a130 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
1a140 68 65 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20  he inserted row 
1a150 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
1a160 72 69 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75  rigger is .** ru
1a170 6e 6e 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20  nning. Once the 
1a180 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1a190 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ends, the value 
1a1a0 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20  returned .** by 
1a1b0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
1a1c0 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20  erts to what it 
1a1d0 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74  was before the t
1a1e0 72 69 67 67 65 72 20 77 61 73 20 66 69 72 65 64  rigger was fired
1a1f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
1a200 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
1a210 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
1a220 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
1a230 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
1a240 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
1a250 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
1a260 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
1a270 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
1a280 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
1a290 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
1a2a0 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
1a2b0 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
1a2c0 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
1a2d0 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
1a2e0 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
1a2f0 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
1a300 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
1a310 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
1a320 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
1a330 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
1a340 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
1a350 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
1a360 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
1a370 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
1a380 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
1a390 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
1a3a0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
1a3b0 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
1a3c0 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
1a3d0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
1a3e0 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
1a3f0 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
1a400 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
1a410 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1a420 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
1a430 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
1a440 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
1a450 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
1a460 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
1a470 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
1a480 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
1a490 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
1a4a0 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
1a4b0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
1a4c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
1a4d0 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
1a4e0 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
1a4f0 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
1a500 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
1a510 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
1a520 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1a530 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
1a540 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
1a550 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
1a560 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
1a570 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
1a580 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1a590 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
1a5a0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
1a5b0 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
1a5c0 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
1a5d0 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
1a5e0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a5f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
1a600 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a610 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
1a620 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
1a630 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
1a640 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
1a650 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
1a660 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
1a670 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1a680 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1a690 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1a6a0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
1a6b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1a6c0 65 74 20 74 68 65 20 4c 61 73 74 20 49 6e 73 65  et the Last Inse
1a6d0 72 74 20 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a  rt Rowid value..
1a6e0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1a6f0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
1a700 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1a710 73 65 72 74 5f 72 6f 77 69 64 28 44 2c 20 52 29  sert_rowid(D, R)
1a720 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74   method allows t
1a730 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
1a740 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20 76 61 6c  o.** set the val
1a750 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 63  ue returned by c
1a760 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c  alling sqlite3_l
1a770 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a780 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74  (D) to R .** wit
1a790 68 6f 75 74 20 69 6e 73 65 72 74 69 6e 67 20 61  hout inserting a
1a7a0 20 72 6f 77 20 69 6e 74 6f 20 74 68 65 20 64 61   row into the da
1a7b0 74 61 62 61 73 65 2e 0a 2a 2f 0a 53 51 4c 49 54  tabase..*/.SQLIT
1a7c0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1a7d0 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65  e3_set_last_inse
1a7e0 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
1a7f0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
1a800 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1a810 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
1a820 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
1a830 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
1a840 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1a850 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
1a860 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1a870 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
1a880 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a  , inserted or.**
1a890 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
1a8a0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
1a8b0 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
1a8c0 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1a8d0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e  .** statement on
1a8e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1a8f0 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69  nnection specifi
1a900 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70  ed by the only p
1a910 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78  arameter..** ^Ex
1a920 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
1a930 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
1a940 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
1a950 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75   modify the valu
1a960 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
1a970 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
1a980 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e  **.** ^Only chan
1a990 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c  ges made directl
1a9a0 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  y by the INSERT,
1a9b0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1a9c0 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a  E statement are.
1a9d0 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20  ** considered - 
1a9e0 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  auxiliary change
1a9f0 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45  s caused by [CRE
1aa00 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
1aa10 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f  iggers], .** [fo
1aa20 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
1aa30 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20  s] or [REPLACE] 
1aa40 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
1aa50 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f  ution are not co
1aa60 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68  unted..** .** Ch
1aa70 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
1aa80 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
1aa90 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53  pted by .** [INS
1aaa0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
1aab0 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  | INSTEAD OF tri
1aac0 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63  ggers] are not c
1aad0 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c  ounted. ^The val
1aae0 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ue .** returned 
1aaf0 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
1ab00 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79  es() immediately
1ab10 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54   after an INSERT
1ab20 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20  , UPDATE or .** 
1ab30 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1ab40 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69   run on a view i
1ab50 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f  s always zero. O
1ab60 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
1ab70 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62   to real .** tab
1ab80 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  les are counted.
1ab90 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72  .**.** Things ar
1aba0 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74  e more complicat
1abb0 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65  ed if the sqlite
1abc0 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
1abd0 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75  tion is.** execu
1abe0 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67  ted while a trig
1abf0 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72  ger program is r
1ac00 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79  unning. This may
1ac10 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a   happen if the.*
1ac20 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74  * program uses t
1ac30 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
1ac40 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20  L function], or 
1ac50 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61  if some other ca
1ac60 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
1ac70 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74  on invokes sqlit
1ac80 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72  e3_changes() dir
1ac90 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c  ectly. Essential
1aca0 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a  ly:.** .** <ul>.
1acb0 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f  **   <li> ^(Befo
1acc0 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72  re entering a tr
1acd0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68  igger program th
1ace0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1acf0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71   by.**        sq
1ad00 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1ad10 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65  function is save
1ad20 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69  d. After the tri
1ad30 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a  gger program .**
1ad40 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69          has fini
1ad50 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e  shed, the origin
1ad60 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74  al value is rest
1ad70 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20  ored.)^.** .**  
1ad80 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61   <li> ^(Within a
1ad90 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1ada0 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50   each INSERT, UP
1adb0 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20  DATE and DELETE 
1adc0 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65  .**        state
1add0 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61  ment sets the va
1ade0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1adf0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1ae00 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f  ) .**        upo
1ae10 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20  n completion as 
1ae20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73  normal. Of cours
1ae30 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69  e, this value wi
1ae40 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a  ll not include .
1ae50 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68  **        any ch
1ae60 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20  anges performed 
1ae70 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c  by sub-triggers,
1ae80 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f   as the sqlite3_
1ae90 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
1aea0 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20       value will 
1aeb0 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73  be saved and res
1aec0 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68  tored after each
1aed0 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73   sub-trigger has
1aee0 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e   run.)^.** </ul>
1aef0 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65  .** .** ^This me
1af00 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20  ans that if the 
1af10 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1af20 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c  nction (or simil
1af30 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62  ar) is used.** b
1af40 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45  y the first INSE
1af50 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1af60 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
1af70 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
1af80 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20   it .** returns 
1af90 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74  the value as set
1afa0 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e   when the callin
1afb0 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61  g statement bega
1afc0 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  n executing..** 
1afd0 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62  ^If it is used b
1afe0 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20  y the second or 
1aff0 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20  subsequent such 
1b000 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1b010 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70   a trigger .** p
1b020 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75  rogram, the valu
1b030 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65  e returned refle
1b040 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  cts the number o
1b050 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20  f rows modified 
1b060 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69  by the .** previ
1b070 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ous INSERT, UPDA
1b080 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1b090 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
1b0a0 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
1b0b0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
1b0c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
1b0d0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
1b0e0 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
1b0f0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
1b100 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
1b110 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1b120 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
1b130 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1b140 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1b150 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1b160 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b170 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1b180 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
1b190 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
1b1a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1b1b0 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
1b1c0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
1b1d0 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  aningful..*/.SQL
1b1e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1b1f0 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
1b200 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1b210 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
1b220 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
1b230 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ified.** METHOD:
1b240 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1b250 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
1b260 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20  turns the total 
1b270 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69  number of rows i
1b280 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65  nserted, modifie
1b290 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d or.** deleted 
1b2a0 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c  by all [INSERT],
1b2b0 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
1b2c0 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
1b2d0 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69   completed.** si
1b2e0 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nce the database
1b2f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20   connection was 
1b300 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e  opened, includin
1b310 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65 64  g those executed
1b320 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74   as.** part of t
1b330 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e  rigger programs.
1b340 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20   ^Executing any 
1b350 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51  other type of SQ
1b360 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64  L statement.** d
1b370 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74  oes not affect t
1b380 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1b390 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74  d by sqlite3_tot
1b3a0 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a  al_changes()..**
1b3b0 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61   .** ^Changes ma
1b3c0 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66  de as part of [f
1b3d0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
1b3e0 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64  ns] are included
1b3f0 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74   in the.** count
1b400 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65  , but those made
1b410 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c   as part of REPL
1b420 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  ACE constraint r
1b430 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a  esolution are.**
1b440 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74   not. ^Changes t
1b450 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
1b460 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
1b470 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
1b480 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74  gers .** are not
1b490 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
1b4a0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
1b4b0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1b4c0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
1b4d0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
1b4e0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
1b4f0 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67  the [total_chang
1b500 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
1b510 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
1b520 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
1b530 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
1b540 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
1b550 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1b560 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
1b570 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
1b580 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
1b590 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
1b5a0 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
1b5b0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
1b5c0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
1b5d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1b5e0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1b5f0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1b600 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
1b610 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
1b620 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
1b630 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1b640 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1b650 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
1b660 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
1b670 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
1b680 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
1b690 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
1b6a0 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
1b6b0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
1b6c0 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
1b6d0 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
1b6e0 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
1b6f0 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
1b700 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
1b710 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
1b720 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
1b730 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
1b740 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
1b750 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
1b760 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
1b770 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
1b780 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
1b790 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
1b7a0 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
1b7b0 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
1b7c0 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
1b7d0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
1b7e0 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
1b7f0 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
1b800 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
1b810 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
1b820 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
1b830 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
1b840 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
1b850 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1b860 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
1b870 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
1b880 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
1b890 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
1b8a0 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
1b8b0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
1b8c0 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
1b8d0 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
1b8e0 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
1b8f0 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
1b900 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
1b910 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
1b920 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
1b930 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
1b940 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
1b950 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
1b960 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
1b970 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
1b980 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
1b990 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
1b9a0 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
1b9b0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
1b9c0 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
1b9d0 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
1b9e0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
1b9f0 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
1ba00 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
1ba10 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
1ba20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
1ba30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1ba40 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
1ba50 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
1ba60 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
1ba70 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
1ba80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
1ba90 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
1baa0 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
1bab0 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
1bac0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1bad0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1bae0 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
1baf0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1bb00 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
1bb10 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
1bb20 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
1bb30 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
1bb40 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
1bb50 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
1bb60 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
1bb70 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1bb80 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
1bb90 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
1bba0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1bbb0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1bbc0 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
1bbd0 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
1bbe0 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
1bbf0 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
1bc00 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1bc10 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
1bc20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
1bc30 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
1bc40 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
1bc50 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
1bc60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1bc70 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
1bc80 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
1bc90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1bca0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1bcb0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1bcc0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1bcd0 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
1bce0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1bcf0 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
1bd00 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
1bd10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1bd20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
1bd30 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
1bd40 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
1bd50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1bd60 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
1bd70 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
1bd80 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
1bd90 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
1bda0 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
1bdb0 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
1bdc0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1bdd0 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
1bde0 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
1bdf0 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
1be00 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
1be10 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
1be20 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
1be30 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
1be40 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
1be50 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
1be60 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
1be70 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
1be80 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
1be90 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
1bea0 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
1beb0 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
1bec0 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
1bed0 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
1bee0 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
1bef0 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
1bf00 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
1bf10 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
1bf20 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
1bf30 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
1bf40 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
1bf50 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
1bf60 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
1bf70 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
1bf80 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
1bf90 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
1bfa0 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
1bfb0 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
1bfc0 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
1bfd0 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
1bfe0 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
1bff0 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
1c000 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
1c010 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
1c020 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
1c030 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
1c040 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
1c050 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1c060 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
1c070 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
1c080 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
1c090 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
1c0a0 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
1c0b0 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
1c0c0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1c0d0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1c0e0 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
1c0f0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1c100 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
1c110 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
1c120 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
1c130 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
1c140 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
1c150 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
1c160 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1c170 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
1c180 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
1c190 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
1c1a0 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
1c1b0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
1c1c0 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
1c1d0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1c1e0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
1c1f0 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
1c200 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
1c210 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
1c220 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1c230 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
1c240 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
1c250 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
1c260 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1c270 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
1c280 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
1c290 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
1c2a0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1c2b0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
1c2c0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
1c2d0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1c2e0 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
1c2f0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
1c300 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
1c310 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
1c320 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1c330 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
1c340 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
1c350 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54   order..*/.SQLIT
1c360 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1c370 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
1c380 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c   char *sql);.SQL
1c390 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1c3a0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
1c3b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
1c3c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c3d0 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
1c3e0 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
1c3f0 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
1c400 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
1c410 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61  {busy-handler ca
1c420 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61  llback} {busy ha
1c430 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44  ndler}.** METHOD
1c440 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1c450 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73  ^The sqlite3_bus
1c460 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29  y_handler(D,X,P)
1c470 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1c480 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1c490 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68  n X.** that migh
1c4a0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
1c4b0 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65  h argument P whe
1c4c0 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
1c4d0 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61  mpt is made to a
1c4e0 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65  ccess a database
1c4f0 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65   table associate
1c500 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62  d with.** [datab
1c510 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1c520 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74  D when another t
1c530 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
1c540 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c  ess has the tabl
1c550 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65  e locked..** The
1c560 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1c570 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63  ndler() interfac
1c580 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70  e is used to imp
1c590 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74  lement.** [sqlit
1c5a0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1c5b0 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62  )] and [PRAGMA b
1c5c0 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a  usy_timeout]..**
1c5d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
1c5e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1c5f0 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
1c600 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75  BUSY].** is retu
1c610 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
1c620 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
1c630 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49  ng the lock.  ^I
1c640 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
1c650 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
1c660 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
1c670 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69  lback might be i
1c680 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
1c690 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
1c6a0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
1c6b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79  ment to the busy
1c6c0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
1c6d0 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
1c6e0 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
1c6f0 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
1c700 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1c710 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1c720 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  .  ^The second a
1c730 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
1c740 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
1c750 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
1c760 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
1c770 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
1c780 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
1c790 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75   invoked previou
1c7a0 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65  sly for the same
1c7b0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
1c7c0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
1c7d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1c7e0 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
1c7f0 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
1c800 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
1c810 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
1c820 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
1c830 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65  BUSY] is returne
1c840 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  d.** to the appl
1c850 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  ication..** ^If 
1c860 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1c870 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
1c880 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
1c890 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
1c8a0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
1c8b0 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79  abase and the cy
1c8c0 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
1c8d0 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
1c8e0 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
1c8f0 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
1c900 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
1c910 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
1c920 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
1c930 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
1c940 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
1c950 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
1c960 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
1c970 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
1c980 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
1c990 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
1c9a0 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
1c9b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1c9c0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1c9d0 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  on instead of in
1c9e0 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62  voking the .** b
1c9f0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  usy handler..** 
1ca00 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61  Consider a scena
1ca10 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72  rio where one pr
1ca20 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
1ca30 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61   a read lock tha
1ca40 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e  t.** it is tryin
1ca50 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  g to promote to 
1ca60 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1ca70 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20  and.** a second 
1ca80 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1ca90 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  ng a reserved lo
1caa0 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72  ck that it is tr
1cab0 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  ying.** to promo
1cac0 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69  te to an exclusi
1cad0 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69  ve lock.  The fi
1cae0 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  rst process cann
1caf0 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65  ot proceed.** be
1cb00 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1cb10 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ked by the secon
1cb20 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  d and the second
1cb30 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a   process cannot.
1cb40 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75  ** proceed becau
1cb50 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1cb60 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20   by the first.  
1cb70 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65  If both processe
1cb80 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  s.** invoke the 
1cb90 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e  busy handlers, n
1cba0 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65  either will make
1cbb0 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20   any progress.  
1cbc0 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51  Therefore,.** SQ
1cbd0 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51  Lite returns [SQ
1cbe0 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74  LITE_BUSY] for t
1cbf0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1cc00 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68  , hoping that th
1cc10 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63  is.** will induc
1cc20 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  e the first proc
1cc30 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69  ess to release i
1cc40 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64  ts read lock and
1cc50 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65   allow.** the se
1cc60 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20  cond process to 
1cc70 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  proceed..**.** ^
1cc80 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79  The default busy
1cc90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1cca0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  L..**.** ^(There
1ccb0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
1ccc0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
1ccd0 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65  er defined for e
1cce0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
1ccf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53   connection].  S
1cd00 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73  etting a new bus
1cd10 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73  y handler clears
1cd20 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73   any.** previous
1cd30 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29  ly set handler.)
1cd40 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61  ^  ^Note that ca
1cd50 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  lling [sqlite3_b
1cd60 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a  usy_timeout()].*
1cd70 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20  * or evaluating 
1cd80 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d  [PRAGMA busy_tim
1cd90 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61  eout=N] will cha
1cda0 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  nge the.** busy 
1cdb0 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73  handler and thus
1cdc0 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69   clear any previ
1cdd0 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68  ously set busy h
1cde0 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
1cdf0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
1ce00 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
1ce10 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
1ce20 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
1ce30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ce40 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1ce50 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1ce60 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  r.  In other wor
1ce70 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20  ds,.** the busy 
1ce80 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72  handler is not r
1ce90 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73  eentrant.  Any s
1cea0 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
1ceb0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
1cec0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
1ced0 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
1cee0 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
1cef0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1cf00 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
1cf10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1cf20 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
1cf30 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1cf40 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  er..*/.SQLITE_AP
1cf50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  I int sqlite3_bu
1cf60 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
1cf70 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a  e3*,int(*)(void*
1cf80 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f  ,int),void*);../
1cf90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1cfa0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
1cfb0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
1cfc0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1cfd0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1cfe0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1cff0 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1d000 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1d010 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1d020 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1d030 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1d040 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1d050 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1d060 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1d070 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1d080 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1d090 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1d0a0 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1d0b0 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1d0c0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1d0d0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1d0e0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1d0f0 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1d100 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1d110 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d120 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1d130 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
1d140 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1d150 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1d160 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1d170 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1d180 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1d190 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1d1a0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1d1b0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1d1c0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1d1d0 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1d1e0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1d1f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
1d200 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1d210 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1d220 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1d230 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1d240 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1d250 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1d260 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1d270 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1d280 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1d290 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1d2a0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
1d2b0 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
1d2c0 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53  sy_timeout].*/.S
1d2d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1d2e0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1d2f0 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
1d300 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
1d310 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
1d320 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
1d330 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
1d340 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1d350 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e3.**.** This is
1d360 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
1d370 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
1d380 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
1d390 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1d3a0 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
1d3b0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
1d3c0 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
1d3d0 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
1d3e0 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
1d3f0 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
1d400 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
1d410 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
1d420 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
1d430 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
1d440 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
1d450 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
1d460 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
1d470 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
1d480 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
1d490 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
1d4a0 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
1d4b0 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
1d4c0 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
1d4d0 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
1d4e0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
1d4f0 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
1d500 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
1d510 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
1d520 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
1d530 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
1d540 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
1d550 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
1d560 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
1d570 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
1d580 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1d590 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
1d5a0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
1d5b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1d5c0 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
1d5d0 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
1d5e0 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
1d5f0 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
1d600 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
1d610 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
1d620 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1d630 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
1d640 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
1d650 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
1d660 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
1d670 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
1d680 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
1d690 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
1d6a0 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
1d6b0 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
1d6c0 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
1d6d0 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
1d6e0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1d6f0 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
1d700 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
1d710 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
1d720 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
1d730 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1d740 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
1d750 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
1d760 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d770 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
1d780 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
1d790 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
1d7a0 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
1d7b0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
1d7c0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
1d7d0 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
1d7e0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1d7f0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
1d800 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
1d810 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
1d820 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
1d830 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
1d840 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
1d850 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1d860 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1d870 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
1d880 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
1d890 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
1d8a0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1d8b0 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
1d8c0 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
1d8d0 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
1d8e0 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
1d8f0 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
1d900 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
1d910 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1d920 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
1d930 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
1d940 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
1d950 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
1d960 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
1d970 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
1d980 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
1d990 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
1d9a0 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
1d9b0 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
1d9c0 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
1d9d0 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
1d9e0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1d9f0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1da00 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1da10 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
1da20 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1da30 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
1da40 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1da50 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
1da60 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
1da70 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
1da80 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
1da90 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
1daa0 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
1dab0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1dac0 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
1dad0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1dae0 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
1daf0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1db00 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
1db10 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
1db20 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
1db30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1db40 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
1db50 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
1db60 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
1db70 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
1db80 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
1db90 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
1dba0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
1dbb0 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
1dbc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
1dbd0 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
1dbe0 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
1dbf0 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
1dc00 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
1dc10 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
1dc20 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
1dc30 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
1dc40 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
1dc50 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
1dc60 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
1dc70 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
1dc80 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
1dc90 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
1dca0 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
1dcb0 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
1dcc0 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
1dcd0 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
1dce0 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
1dcf0 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
1dd00 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
1dd10 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
1dd20 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1dd30 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
1dd40 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
1dd50 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
1dd60 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
1dd70 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
1dd80 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
1dd90 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
1dda0 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
1ddb0 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
1ddc0 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
1ddd0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
1dde0 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
1ddf0 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
1de00 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
1de10 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
1de20 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
1de30 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1de40 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
1de50 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
1de60 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
1de70 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
1de80 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
1de90 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
1dea0 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
1deb0 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
1dec0 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
1ded0 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
1dee0 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
1def0 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
1df00 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1df10 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
1df20 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
1df30 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
1df40 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
1df50 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
1df60 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
1df70 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
1df80 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  rmsg()]..*/.SQLI
1df90 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1dfa0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1dfb0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1dfc0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1dfd0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1dfe0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1dff0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1e000 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1e010 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1e020 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1e030 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1e040 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1e050 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1e060 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1e070 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1e080 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1e090 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1e0a0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1e0b0 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1e0c0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1e0d0 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1e0e0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1e0f0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53  ten here */.);.S
1e100 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1e110 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1e120 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
1e130 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e140 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
1e150 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
1e160 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1e170 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1e180 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
1e190 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
1e1a0 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
1e1b0 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
1e1c0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1e1d0 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
1e1e0 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d  nes understand m
1e1f0 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f  ost of the commo
1e200 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e 67  n K&R formatting
1e210 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75   options,.** plu
1e220 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61  s some additiona
1e230 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66  l non-standard f
1e240 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 64  ormats, detailed
1e250 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20   below..** Note 
1e260 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 65  that some of the
1e270 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 6f   more obscure fo
1e280 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1e290 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20   from recent.** 
1e2a0 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 61  C-library standa
1e2b0 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 20  rds are omitted 
1e2c0 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d  from this implem
1e2d0 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  entation..**.** 
1e2e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1e2f0 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1e300 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1e310 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1e320 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1e330 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1e340 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1e350 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1e360 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1e370 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1e380 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1e390 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1e3a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1e3b0 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1e3c0 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1e3d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1e3e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1e3f0 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1e400 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1e410 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1e420 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1e430 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1e440 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1e450 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1e460 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1e470 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1e480 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1e490 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1e4a0 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1e4b0 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1e4c0 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1e4d0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1e4e0 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1e4f0 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1e500 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1e510 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1e520 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1e530 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1e540 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1e550 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1e560 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1e570 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1e580 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1e590 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1e5a0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1e5b0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1e5c0 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1e5d0 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1e5e0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1e5f0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1e600 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1e610 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1e620 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1e630 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1e640 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1e650 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1e660 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1e670 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1e680 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1e690 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1e6a0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1e6b0 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1e6c0 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1e6d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1e6e0 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1e6f0 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1e700 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1e710 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1e720 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1e730 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1e740 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1e750 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1e760 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1e770 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1e780 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1e790 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1e7a0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1e7b0 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1e7c0 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1e7d0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1e7e0 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1e7f0 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1e800 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1e810 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1e820 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1e830 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1e840 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1e850 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1e860 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e870 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1e880 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1e890 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1e8a0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1e8b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1e8c0 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1e8d0 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1e8e0 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1e8f0 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1e900 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1e910 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1e920 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1e930 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1e940 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1e950 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1e960 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1e970 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1e980 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 20  %q", "%Q", "%w" 
1e990 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1e9a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1e9b0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1e9c0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1e9d0 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1e9e0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1e9f0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1ea00 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1ea10 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1ea20 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1ea30 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1ea40 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1ea50 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1ea60 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1ea70 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1ea80 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1ea90 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1eaa0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1eab0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1eac0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1ead0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1eae0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1eaf0 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1eb00 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1eb10 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1eb20 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1eb30 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1eb40 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1eb50 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1eb60 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1eb70 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1eb80 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1eb90 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1eba0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1ebb0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1ebc0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1ebd0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1ebe0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1ebf0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1ec00 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1ec10 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1ec20 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1ec30 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1ec40 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1ec50 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1ec60 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ec70 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1ec80 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1ec90 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1eca0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1ecb0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1ecc0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1ecd0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1ece0 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1ecf0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1ed00 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1ed10 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1ed20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1ed30 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1ed40 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1ed50 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1ed60 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1ed70 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1ed80 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1ed90 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1eda0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1edb0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1edc0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1edd0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1ede0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1edf0 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1ee00 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1ee10 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1ee20 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1ee30 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1ee40 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1ee50 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1ee60 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1ee70 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1ee80 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1ee90 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1eea0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1eeb0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1eec0 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1eed0 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1eee0 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1eef0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1ef00 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1ef10 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1ef20 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1ef30 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1ef40 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1ef50 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1ef60 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1ef70 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1ef80 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1ef90 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1efa0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1efb0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1efc0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1efd0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1efe0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1eff0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1f000 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1f010 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1f020 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1f030 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1f040 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1f050 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1f060 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1f070 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1f080 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1f090 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1f0a0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1f0b0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1f0c0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1f0d0 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1f0e0 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1f0f0 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1f100 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1f110 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1f120 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b  ng option is lik
1f130 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74 68  e "%q" except th
1f140 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74 6f  at it expects to
1f150 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 64  .** be contained
1f160 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71   within double-q
1f170 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f 66  uotes instead of
1f180 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20   single quotes, 
1f190 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 65  and it.** escape
1f1a0 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f  s the double-quo
1f1b0 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e 73  te character ins
1f1c0 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e 67  tead of the sing
1f1d0 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72  le-quote.** char
1f1e0 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 25  acter.)^  The "%
1f1f0 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
1f200 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 64  tion is intended
1f210 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 65   for safely inse
1f220 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61  rting.** table a
1f230 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20  nd column names 
1f240 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 74  into a construct
1f250 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1f260 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1f270 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1f280 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1f290 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1f2a0 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1f2b0 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1f2c0 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1f2d0 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1f2e0 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1f2f0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f300 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1f310 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1f320 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
1f330 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d   char *sqlite3_m
1f340 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1f350 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  r*,...);.SQLITE_
1f360 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
1f370 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1f380 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1f390 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1f3a0 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
1f3b0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1f3c0 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
1f3d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1f3e0 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
1f3f0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1f400 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1f410 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
1f420 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1f430 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
1f440 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
1f450 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
1f460 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
1f470 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
1f480 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
1f490 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1f4a0 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
1f4b0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1f4c0 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
1f4d0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
1f4e0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
1f4f0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
1f500 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
1f510 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
1f520 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
1f530 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1f540 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
1f550 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
1f560 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f570 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1f580 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1f590 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
1f5a0 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
1f5b0 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
1f5c0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
1f5d0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
1f5e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f5f0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
1f600 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
1f610 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
1f620 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
1f630 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
1f640 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
1f650 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
1f660 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1f670 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
1f680 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f690 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
1f6a0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1f6b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1f6c0 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69  alloc64(N) routi
1f6d0 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69  ne works just li
1f6e0 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ke.** sqlite3_ma
1f6f0 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74  lloc(N) except t
1f700 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69  hat N is an unsi
1f710 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65  gned 64-bit inte
1f720 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1f730 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69  f a signed 32-bi
1f740 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  t integer..**.**
1f750 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
1f760 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20  3_free() with a 
1f770 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73  pointer previous
1f780 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ly returned.** b
1f790 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1f7a0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1f7b0 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73  alloc() releases
1f7c0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a   that memory so.
1f7d0 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  ** that it might
1f7e0 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68   be reused.  ^Th
1f7f0 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
1f800 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
1f810 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
1f820 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
1f830 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
1f840 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
1f850 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
1f860 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
1f870 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
1f880 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
1f890 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
1f8a0 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
1f8b0 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
1f8c0 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
1f8d0 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
1f8e0 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
1f8f0 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
1f900 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
1f910 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
1f920 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
1f930 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
1f940 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
1f950 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
1f960 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
1f970 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1f980 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
1f990 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
1f9a0 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
1f9b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1f9c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1f9d0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1f9e0 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  c()..**.** ^The 
1f9f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1fa00 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61  X,N) interface a
1fa10 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a  ttempts to resiz
1fa20 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d  e a.** prior mem
1fa30 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58  ory allocation X
1fa40 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
1fa50 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  N bytes..** ^If 
1fa60 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20  the X parameter 
1fa70 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1fa80 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20  oc(X,N).** is a 
1fa90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1faa0 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
1fab0 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
1fac0 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1fad0 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20  3_malloc(N)..** 
1fae0 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65  ^If the N parame
1faf0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1fb00 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a  ealloc(X,N) is z
1fb10 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
1fb20 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
1fb30 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
1fb40 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
1fb50 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
1fb60 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69  ree(X)..** ^sqli
1fb70 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1fb80 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1fb90 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
1fba0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
1fbb0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1fbc0 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
1fbd0 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74   if insufficient
1fbe0 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c   memory is avail
1fbf0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
1fc00 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1fc10 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1fc20 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
1fc30 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
1fc40 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1fc50 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
1fc60 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
1fc70 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
1fc80 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1fc90 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61  3_realloc(X,N) a
1fca0 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1fcb0 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1fcc0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1fcd0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65  _realloc(X,N) re
1fce0 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e  turns NULL and N
1fcf0 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68   is positive, th
1fd00 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20  en the.** prior 
1fd10 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f  allocation is no
1fd20 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
1fd30 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1fd40 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72  loc64(X,N) inter
1fd50 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20  faces works the 
1fd60 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74  same as.** sqlit
1fd70 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1fd80 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73  except that N is
1fd90 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e   a 64-bit unsign
1fda0 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65  ed integer inste
1fdb0 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69  ad.** of a 32-bi
1fdc0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
1fdd0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73  ..**.** ^If X is
1fde0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1fdf0 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  tion previously 
1fe00 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
1fe10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a  lite3_malloc(),.
1fe20 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1fe30 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  c64(), sqlite3_r
1fe40 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c  ealloc(), or sql
1fe50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29  ite3_realloc64()
1fe60 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
1fe70 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
1fe80 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  ns the size of t
1fe90 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hat memory alloc
1fea0 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a  ation in bytes..
1feb0 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  ** ^The value re
1fec0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1fed0 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74  3_msize(X) might
1fee0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
1fef0 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66  the number.** of
1ff00 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65 64   bytes requested
1ff10 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f   when X was allo
1ff20 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73  cated.  ^If X is
1ff30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1ff40 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
1ff50 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73  msize(X) returns
1ff60 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69   zero.  If X poi
1ff70 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67  nts to something
1ff80 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20   that is not.** 
1ff90 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
1ffa0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1ffb0 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69  on, or if it poi
1ffc0 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c  nts to a formerl
1ffd0 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72  y.** valid memor
1ffe0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61  y allocation tha
1fff0 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66  t has now been f
20000 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  reed, then the b
20010 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71  ehavior.** of sq
20020 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69  lite3_msize(X) i
20030 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
20040 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c  possibly harmful
20050 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
20060 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
20070 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20080 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
20090 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
200a0 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20  malloc64(), and 
200b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
200c0 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  4().** is always
200d0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c   aligned to at l
200e0 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62  east an 8 byte b
200f0 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61  oundary, or to a
20100 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64  .** 4 byte bound
20110 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49  ary if the [SQLI
20120 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45  TE_4_BYTE_ALIGNE
20130 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c  D_MALLOC] compil
20140 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
20150 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
20160 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  In SQLite versio
20170 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e  n 3.5.0 and 3.5.
20180 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62  1, it was possib
20190 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20  le to define.** 
201a0 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  the SQLITE_OMIT_
201b0 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f  MEMORY_ALLOCATIO
201c0 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61  N which would ca
201d0 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  use the built-in
201e0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
201f0 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  on of these rout
20200 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74  ines to be omitt
20210 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69  ed.  That capabi
20220 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f  lity.** is no lo
20230 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20  nger provided.  
20240 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65  Only built-in me
20250 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20  mory allocators 
20260 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a  can be used..**.
20270 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69  ** Prior to SQLi
20280 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31  te version 3.7.1
20290 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f  0, the Windows O
202a0 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
202b0 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20  r called.** the 
202c0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
202d0 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
202e0 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
202f0 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
20300 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
20310 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
20320 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
20330 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
20340 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
20350 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
20360 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
20370 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
20380 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
20390 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64  on errors were d
203a0 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20  etected, but.** 
203b0 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74  they were report
203c0 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
203d0 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
203e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
203f0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
20400 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
20410 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
20420 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
20430 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
20440 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
20450 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
20460 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
20470 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
20480 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
20490 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
204a0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
204b0 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
204c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
204d0 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
204e0 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
204f0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
20500 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
20510 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
20520 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
20530 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
20540 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
20550 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
20560 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
20570 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
20580 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
20590 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
205a0 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
205b0 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  (int);.SQLITE_AP
205c0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
205d0 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 33  malloc64(sqlite3
205e0 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  _uint64);.SQLITE
205f0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
20600 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
20610 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
20620 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
20630 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a  _realloc64(void*
20640 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
20650 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
20660 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
20670 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
20680 50 49 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  PI sqlite3_uint6
20690 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  4 sqlite3_msize(
206a0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
206b0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
206c0 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
206d0 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
206e0 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
206f0 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
20700 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
20710 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
20720 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
20730 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
20740 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
20750 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
20760 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
20770 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
20780 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
20790 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
207a0 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
207b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
207c0 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
207d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
207e0 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
207f0 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
20800 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
20810 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
20820 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
20830 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
20840 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
20850 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
20860 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
20870 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
20880 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
20890 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
208a0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
208b0 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
208c0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
208d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
208e0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
208f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
20900 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
20910 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
20920 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
20930 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
20940 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
20950 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
20960 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
20970 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
20980 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
20990 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
209a0 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
209b0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
209c0 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
209d0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
209e0 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
209f0 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
20a00 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
20a10 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
20a20 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
20a30 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
20a40 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
20a50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
20a60 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
20a70 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
20a80 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
20a90 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
20aa0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
20ab0 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
20ac0 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
20ad0 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
20ae0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
20af0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
20b00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
20b10 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
20b20 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
20b30 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
20b40 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
20b50 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
20b60 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
20b70 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
20b80 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
20b90 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
20ba0 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
20bb0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
20bc0 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
20bd0 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
20be0 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
20bf0 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
20c00 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
20c10 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
20c20 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
20c30 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
20c40 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
20c50 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
20c60 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
20c70 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
20c80 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
20c90 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
20ca0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
20cb0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
20cc0 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
20cd0 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
20ce0 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
20cf0 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
20d00 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
20d10 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
20d20 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
20d30 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
20d40 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54   buffer P..** ^T
20d50 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 63  he P parameter c
20d60 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  an be a NULL poi
20d70 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  nter..**.** ^If 
20d80 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73  this routine has
20d90 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f   not been previo
20da0 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69  usly called or i
20db0 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a  f the previous.*
20dc0 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73  * call had N les
20dd0 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20  s than one or a 
20de0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
20df0 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 4e   P, then the PRN
20e00 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 75  G is.** seeded u
20e10 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
20e20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 68  obtained from th
20e30 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
20e40 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64  thod of.** the d
20e50 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
20e60 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
20e70 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 73  ^If the previous
20e80 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
20e90 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f  utine had an N o
20ea0 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20  f 1 or more and 
20eb0 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20  a.** non-NULL P 
20ec0 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f 2d  then the pseudo-
20ed0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
20ee0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
20ef0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
20f00 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
20f10 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
20f20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
20f30 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ethod..*/.SQLITE
20f40 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
20f50 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
20f60 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
20f70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
20f80 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
20f90 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
20fa0 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  cks.** METHOD: s
20fb0 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59 57 4f 52  qlite3.** KEYWOR
20fc0 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a 65 72 20  DS: {authorizer 
20fd0 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20  callback}.**.** 
20fe0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
20ff0 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
21000 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
21010 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
21020 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
21030 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
21040 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
21050 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
21060 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21070 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
21080 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
21090 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
210a0 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
210b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
210c0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
210d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
210e0 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
210f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
21100 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  )], [sqlite3_pre
21110 70 61 72 65 31 36 28 29 5d 2c 20 5b 73 71 6c 69  pare16()], [sqli
21120 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
21130 28 29 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  ()],.** and [sql
21140 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
21150 33 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  3()].  ^At vario
21160 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
21170 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
21180 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
21190 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
211a0 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
211b0 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
211c0 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
211d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
211e0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
211f0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
21200 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
21210 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
21220 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
21230 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
21240 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
21250 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
21260 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
21270 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
21280 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
21290 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
212a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
212b0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
212c0 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
212d0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
212e0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
212f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
21300 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
21310 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
21320 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
21330 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
21340 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
21350 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
21360 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
21370 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
21380 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
21390 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
213a0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
213b0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
213c0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
213d0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
213e0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
213f0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
21400 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
21410 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
21420 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
21430 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
21440 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
21450 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
21460 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
21470 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
21480 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
21490 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
214a0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
214b0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
214c0 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
214d0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
214e0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
214f0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
21500 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
21510 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
21520 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
21530 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
21540 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21550 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
21560 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
21570 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21580 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
21590 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
215a0 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
215b0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
215c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
215d0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
215e0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
215f0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
21600 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
21610 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
21620 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
21630 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
21640 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
21650 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
21660 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65 69 74  callback are eit
21670 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  her NULL pointer
21680 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s or zero-termin
21690 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ated strings.** 
216a0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
216b0 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20  itional details 
216c0 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
216d0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
216e0 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  d..** Applicatio
216f0 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73 20 62  ns must always b
21700 65 20 70 72 65 70 61 72 65 64 20 74 6f 20 65 6e  e prepared to en
21710 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70  counter a NULL p
21720 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a  ointer in any.**
21730 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 74 68   of the third th
21740 72 6f 75 67 68 20 74 68 65 20 73 69 78 74 68 20  rough the sixth 
21750 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
21760 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e authorization 
21770 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
21780 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
21790 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
217a0 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
217b0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
217c0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
217d0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
217e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
217f0 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
21800 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
21810 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
21820 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
21830 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
21840 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
21850 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
21860 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
21870 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
21880 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
21890 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
218a0 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
218b0 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
218c0 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
218d0 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
218e0 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
218f0 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61  able..** ^When a
21900 20 74 61 62 6c 65 20 69 73 20 72 65 66 65 72 65   table is refere
21910 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c 45 43  nced by a [SELEC
21920 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e  T] but no column
21930 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65   values are.** e
21940 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20 74 68  xtracted from th
21950 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20 65 78  at table (for ex
21960 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65 72 79  ample in a query
21970 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54   like.** "SELECT
21980 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74   count(*) FROM t
21990 61 62 22 29 20 74 68 65 6e 20 74 68 65 20 5b 53  ab") then the [S
219a0 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75 74 68  QLITE_READ] auth
219b0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
219c0 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ** is invoked on
219d0 63 65 20 66 6f 72 20 74 68 61 74 20 74 61 62 6c  ce for that tabl
219e0 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20  e with a column 
219f0 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61 6e 20  name that is an 
21a00 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
21a10 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
21a20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
21a30 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
21a40 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
21a50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
21a60 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
21a70 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
21a80 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
21a90 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
21aa0 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
21ab0 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
21ac0 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
21ad0 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
21ae0 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
21af0 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
21b00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21b10 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
21b20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
21b30 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
21b40 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
21b50 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
21b60 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
21b70 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
21b80 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
21b90 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
21ba0 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
21bb0 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
21bc0 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
21bd0 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
21be0 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
21bf0 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
21c00 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
21c10 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
21c20 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
21c30 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
21c40 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
21c50 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
21c60 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
21c70 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
21c80 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
21c90 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
21ca0 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
21cb0 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
21cc0 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
21cd0 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
21ce0 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
21cf0 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
21d00 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
21d10 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
21d20 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
21d30 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
21d40 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
21d50 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
21d60 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
21d70 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
21d80 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
21d90 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
21da0 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
21db0 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
21dc0 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
21dd0 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
21de0 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
21df0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
21e00 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
21e10 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
21e20 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
21e30 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
21e40 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
21e50 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
21e60 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
21e70 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
21e80 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
21e90 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
21ea0 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
21eb0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
21ec0 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
21ed0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
21ee0 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
21ef0 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
21f00 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
21f10 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
21f20 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
21f30 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
21f40 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
21f50 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
21f60 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
21f70 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
21f80 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
21f90 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
21fa0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
21fb0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
21fc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
21fd0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
21fe0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21ff0 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
22000 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
22010 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
22020 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
22030 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
22040 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
22050 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
22060 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
22070 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
22080 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
22090 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
220a0 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
220b0 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
220c0 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
220d0 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
220e0 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
220f0 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
22100 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
22110 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
22120 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
22130 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
22140 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
22150 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
22160 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22170 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
22180 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
22190 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
221a0 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
221b0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
221c0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
221d0 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
221e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
221f0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
22200 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
22210 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
22220 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
22230 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
22240 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
22250 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
22260 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
22270 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
22280 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
22290 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
222a0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
222b0 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
222c0 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
222d0 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
222e0 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c  a change..*/.SQL
222f0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
22300 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
22310 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
22320 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
22330 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
22340 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
22350 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
22360 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
22370 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
22380 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22390 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
223a0 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
223b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
223c0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
223d0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
223e0 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
223f0 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
22400 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
22410 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
22420 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
22430 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
22440 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
22450 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
22460 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
22470 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
22480 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
22490 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
224a0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
224b0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
224c0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
224d0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
224e0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20  QLITE_IGNORE is 
224f0 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b  also used as a [
22500 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 74  conflict resolut
22510 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74  ion mode].** ret
22520 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 5b  urned from the [
22530 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
22540 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65  conflict()] inte
22550 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
22560 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20  e SQLITE_DENY   
22570 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65  1   /* Abort the
22580 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
22590 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ith an error */.
225a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
225b0 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e  GNORE 2   /* Don
225c0 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c  't allow access,
225d0 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72   but don't gener
225e0 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a  ate an error */.
225f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22600 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69   Authorizer Acti
22610 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
22620 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
22630 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e  authorizer()] in
22640 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
22650 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
22660 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73  ction.** that is
22670 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68   invoked to auth
22680 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51  orize certain SQ
22690 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69  L statement acti
226a0 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ons.  The.** sec
226b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
226c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
226d0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
226e0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
226f0 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69  ** what action i
22700 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a  s being authoriz
22710 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74  ed.  These are t
22720 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f  he integer actio
22730 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20  n codes that.** 
22740 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
22750 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70  allback may be p
22760 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  assed..**.** The
22770 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76  se action code v
22780 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68  alues signify wh
22790 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61  at kind of opera
227a0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a  tion is to be.**
227b0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
227c0 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61  e 3rd and 4th pa
227d0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20  rameters to the 
227e0 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a  authorization.**
227f0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
22800 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d  on will be param
22810 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65  eters or NULL de
22820 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68  pending on which
22830 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64   of these.** cod
22840 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68  es is used as th
22850 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
22860 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70  er.  ^(The 5th p
22870 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a  arameter to the.
22880 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ** authorizer ca
22890 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61  llback is the na
228a0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
228b0 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d  se ("main", "tem
228c0 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20  p",.** etc.) if 
228d0 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e  applicable.)^  ^
228e0 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65  The 6th paramete
228f0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
22900 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
22910 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
22920 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72  he inner-most tr
22930 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68  igger or view th
22940 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  at is responsibl
22950 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63  e for.** the acc
22960 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e  ess attempt or N
22970 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65  ULL if this acce
22980 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69  ss attempt is di
22990 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74  rectly from.** t
229a0 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64  op-level SQL cod
229b0 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..*/./*********
229c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
229d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
229e0 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 3rd *********
229f0 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 4th ********
22a00 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ***/.#define SQL
22a10 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58  ITE_CREATE_INDEX
22a20 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a            1   /*
22a30 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
22a40 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22a50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22a60 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20  TE_CREATE_TABLE 
22a70 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20           2   /* 
22a80 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22a90 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22aa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22ab0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e  E_CREATE_TEMP_IN
22ac0 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49  DEX     3   /* I
22ad0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
22ae0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22af0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22b00 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42  _CREATE_TEMP_TAB
22b10 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61  LE     4   /* Ta
22b20 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22b30 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22b40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22b50 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47  CREATE_TEMP_TRIG
22b60 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69  GER   5   /* Tri
22b70 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
22b80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22b90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22ba0 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20  REATE_TEMP_VIEW 
22bb0 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77       6   /* View
22bc0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
22bd0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22be0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22bf0 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20  EATE_TRIGGER    
22c00 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67      7   /* Trigg
22c10 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
22c20 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22c30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22c40 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20  ATE_VIEW        
22c50 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e     8   /* View N
22c60 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
22c70 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22c80 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45  fine SQLITE_DELE
22c90 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
22ca0 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    9   /* Table N
22cb0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22cc0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22cd0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22ce0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
22cf0 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  10   /* Index Na
22d00 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
22d10 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22d20 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
22d30 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31  ABLE           1
22d40 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  1   /* Table Nam
22d50 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22d60 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22d70 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
22d80 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32  MP_INDEX      12
22d90 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
22da0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
22db0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22dc0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
22dd0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20  P_TABLE      13 
22de0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22df0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22e00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22e10 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
22e20 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20  _TRIGGER    14  
22e30 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
22e40 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
22e50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22e60 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
22e70 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20  VIEW       15   
22e80 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
22e90 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22ea0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22eb0 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45  LITE_DROP_TRIGGE
22ec0 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f  R         16   /
22ed0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
22ee0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22ef0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22f00 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20  ITE_DROP_VIEW   
22f10 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a           17   /*
22f20 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
22f30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22f40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22f50 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20  TE_INSERT       
22f60 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20          18   /* 
22f70 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22f80 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22f90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22fa0 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  E_PRAGMA        
22fb0 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50         19   /* P
22fc0 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31  ragma Name     1
22fd0 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a  st arg or NULL *
22fe0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22ff0 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
23000 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61        20   /* Ta
23010 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
23020 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
23030 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23040 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
23050 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c       21   /* NUL
23060 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c  L            NUL
23070 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23080 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
23090 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20  RANSACTION      
230a0 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72      22   /* Oper
230b0 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c  ation       NULL
230c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
230d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50  define SQLITE_UP
230e0 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  DATE            
230f0 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65     23   /* Table
23100 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
23110 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
23120 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54  efine SQLITE_ATT
23130 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
23140 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61    24   /* Filena
23150 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  me        NULL  
23160 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23170 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41  fine SQLITE_DETA
23180 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
23190 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   25   /* Databas
231a0 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20  e Name   NULL   
231b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
231c0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52  ine SQLITE_ALTER
231d0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
231e0 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  26   /* Database
231f0 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61   Name   Table Na
23200 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
23210 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45  ne SQLITE_REINDE
23220 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  X              2
23230 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  7   /* Index Nam
23240 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
23250 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23260 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45  e SQLITE_ANALYZE
23270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38                28
23280 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
23290 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
232a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
232b0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
232c0 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20  TABLE        29 
232d0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
232e0 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
232f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23300 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42  SQLITE_DROP_VTAB
23310 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20  LE          30  
23320 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
23330 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
23340 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23350 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20  QLITE_FUNCTION  
23360 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20             31   
23370 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20  /* NULL         
23380 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65     Function Name
23390 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
233a0 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20  LITE_SAVEPOINT  
233b0 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f            32   /
233c0 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20  * Operation     
233d0 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65    Savepoint Name
233e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
233f0 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20  ITE_COPY        
23400 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a            0   /*
23410 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20   No longer used 
23420 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23430 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 20  E_RECURSIVE     
23440 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 4e         33   /* N
23450 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
23460 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
23470 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
23480 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
23490 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
234a0 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
234b0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73  lite3.**.** Thes
234c0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
234d0 65 70 72 65 63 61 74 65 64 2e 20 55 73 65 20 74  eprecated. Use t
234e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
234f0 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  e_v2()] interfac
23500 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 20  e.** instead of 
23510 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64 65 73  the routines des
23520 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  cribed here..**.
23530 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
23540 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
23550 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
23560 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
23570 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
23580 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
23590 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
235a0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
235b0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
235c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
235d0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
235e0 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
235f0 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
23600 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
23610 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
23620 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
23630 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
23640 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
23650 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
23660 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
23670 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
23680 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
23690 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
236a0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
236b0 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
236c0 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
236d0 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
236e0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
236f0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
23700 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
23710 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
23720 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
23730 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
23740 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
23750 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
23760 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
23770 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
23780 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  .)^.**.** The [S
23790 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45  QLITE_TRACE_SIZE
237a0 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d  _LIMIT] compile-
237b0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20  time option can 
237c0 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74  be used to limit
237d0 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  .** the length o
237e0 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  f [bound paramet
237f0 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e  er] expansion in
23800 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73   the output of s
23810 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a  qlite3_trace()..
23820 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
23830 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
23840 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
23850 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
23860 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
23870 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
23880 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65   finishes.  ^The
23890 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
238a0 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68  k contains.** th
238b0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
238c0 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e  ment text and an
238d0 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c   estimate of wal
238e0 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20  l-clock time.** 
238f0 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74  of how long that
23900 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20   statement took 
23910 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72  to run.  ^The pr
23920 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  ofile callback.*
23930 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69  * time is in uni
23940 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  ts of nanosecond
23950 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63  s, however the c
23960 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
23970 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79  ation.** is only
23980 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c   capable of mill
23990 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69  isecond resoluti
239a0 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65  on so the six le
239b0 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a  ast significant.
239c0 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65  ** digits in the
239d0 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e   time are meanin
239e0 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76  gless.  Future v
239f0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
23a00 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69  e.** might provi
23a10 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c  de greater resol
23a20 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f  ution on the pro
23a30 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  filer callback. 
23a40 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
23a50 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69  profile() functi
23a60 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  on is considered
23a70 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e   experimental an
23a80 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20  d is.** subject 
23a90 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  to change in fut
23aa0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
23ab0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
23ac0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
23ad0 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
23ae0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
23af0 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
23b00 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
23b10 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
23b20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
23b30 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
23b40 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
23b50 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
23b60 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
23b70 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
23b80 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
23b90 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
23ba0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
23bb0 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 43  QL Trace Event C
23bc0 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
23bd0 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a  : SQLITE_TRACE.*
23be0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
23bf0 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 6c  ants identify cl
23c00 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 20  asses of events 
23c10 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69  that can be moni
23c20 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74  tored.** using t
23c30 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  he [sqlite3_trac
23c40 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 20  e_v2()] tracing 
23c50 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69 72  logic.  The thir
23c60 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  d argument.** to
23c70 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
23c80 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65  v2()] is an OR-e
23c90 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
23ca0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a   one or more of.
23cb0 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** the following
23cc0 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68   constants.  ^Th
23cd0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
23ce0 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 61   to the trace ca
23cf0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65  llback.** is one
23d00 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
23d10 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a  g constants..**.
23d20 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63  ** New tracing c
23d30 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
23d40 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
23d50 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
23d60 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  ^A trace callbac
23d70 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d  k has four argum
23d80 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28  ents: xCallback(
23d90 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68  T,C,P,X)..** ^Th
23da0 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e T argument is 
23db0 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67  one of the integ
23dc0 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 62  er type codes ab
23dd0 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ove..** ^The C a
23de0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
23df0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
23e00 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
23e10 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  in as the.** fou
23e20 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
23e30 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
23e40 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61  2()]..** The P a
23e50 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61  nd X arguments a
23e60 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73  re pointers whos
23e70 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e  e meanings depen
23e80 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64  d on T..**.** <d
23e90 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  l>.** [[SQLITE_T
23ea0 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e  RACE_STMT]] <dt>
23eb0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
23ec0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  T</dt>.** <dd>^A
23ed0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  n SQLITE_TRACE_S
23ee0 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  TMT callback is 
23ef0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70  invoked when a p
23f00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23f10 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e  t.** first begin
23f20 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f  s running and po
23f30 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20  ssibly at other 
23f40 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65  times during the
23f50 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  .** execution of
23f60 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
23f70 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73  atement, such as
23f80 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f 66   at the start of
23f90 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72   each.** trigger
23fa0 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68   subprogram. ^Th
23fb0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
23fc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
23fd0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
23fe0 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58  atement]. ^The X
23ff0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
24000 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
24010 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  ng which.** is t
24020 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51  he unexpanded SQ
24030 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 72  L text of the pr
24040 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24050 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65   or an SQL comme
24060 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  nt .** that indi
24070 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61  cates the invoca
24080 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65  tion of a trigge
24090 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  r.  ^The callbac
240a0 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a  k can compute.**
240b0 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 74   the same text t
240c0 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62  hat would have b
240d0 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  een returned by 
240e0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
240f0 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20  te3_trace()].** 
24100 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 69  interface by usi
24110 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  ng the X argumen
24120 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20  t when X begins 
24130 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e  with "--" and in
24140 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  voking.** [sqlit
24150 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
24160 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  P)] otherwise..*
24170 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
24180 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64  ACE_PROFILE]] <d
24190 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  t>SQLITE_TRACE_P
241a0 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ROFILE</dt>.** <
241b0 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
241c0 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
241d0 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70  back provides ap
241e0 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20  proximately the 
241f0 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  same.** informat
24200 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64  ion as is provid
24210 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
24220 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61  e3_profile()] ca
24230 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
24240 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
24250 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
24260 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24270 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58  nt] and the.** X
24280 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
24290 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74   to a 64-bit int
242a0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74 68  eger which is th
242b0 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a  e estimated of.*
242c0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
242d0 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20  nanosecond that 
242e0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
242f0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
24300 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  un..** ^The SQLI
24310 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
24320 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
24330 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 74  oked when the st
24340 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
24350 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
24360 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74  _TRACE_ROW]] <dt
24370 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f  >SQLITE_TRACE_RO
24380 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  W</dt>.** <dd>^A
24390 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  n SQLITE_TRACE_R
243a0 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  OW callback is i
243b0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
243c0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
243d0 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65  atement generate
243e0 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  s a single row o
243f0 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e  f result.  .** ^
24400 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
24410 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
24420 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
24430 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a  tement] and the.
24440 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73  ** X argument is
24450 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   unused..**.** [
24460 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c  [SQLITE_TRACE_CL
24470 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  OSE]] <dt>SQLITE
24480 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74  _TRACE_CLOSE</dt
24490 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
244a0 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
244b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
244c0 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62  ked when a datab
244d0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
244e0 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68  n closes..** ^Th
244f0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
24500 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
24510 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24520 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a  ction] object.**
24530 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d   and the X argum
24540 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
24550 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
24560 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
24570 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a  STMT       0x01.
24580 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
24590 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20  RACE_PROFILE    
245a0 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x02.#define SQL
245b0 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20  ITE_TRACE_ROW   
245c0 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e       0x04.#defin
245d0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  e SQLITE_TRACE_C
245e0 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a  LOSE      0x08..
245f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24600 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a  SQL Trace Hook.*
24610 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
24620 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
24630 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c  ite3_trace_v2(D,
24640 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  M,X,P) interface
24650 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72 61   registers a tra
24660 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  ce callback.** f
24670 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73  unction X agains
24680 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  t [database conn
24690 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67  ection] D, using
246a0 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d   property mask M
246b0 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20  .** and context 
246c0 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20  pointer P.  ^If 
246d0 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  the X callback i
246e0 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20  s.** NULL or if 
246f0 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65  the M mask is ze
24700 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67  ro, then tracing
24710 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54   is disabled.  T
24720 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74  he.** M argument
24730 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62   should be the b
24740 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d  itwise OR-ed com
24750 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a  bination of.** z
24760 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c  ero or more [SQL
24770 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74  ITE_TRACE] const
24780 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  ants..**.** ^Eac
24790 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  h call to either
247a0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
247b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63   or sqlite3_trac
247c0 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 73  e_v2() overrides
247d0 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61   .** (cancels) a
247e0 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74  ny prior calls t
247f0 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  o sqlite3_trace(
24800 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
24810 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  ce_v2()..**.** ^
24820 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69  The X callback i
24830 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  s invoked whenev
24840 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76  er any of the ev
24850 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 20  ents identified 
24860 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63  by .** mask M oc
24870 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67  cur.  ^The integ
24880 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  er return value 
24890 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63  from the callbac
248a0 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a  k is currently.*
248b0 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67  * ignored, thoug
248c0 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67  h this may chang
248d0 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  e in future rele
248e0 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a  ases.  Callback.
248f0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
24900 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ns should return
24910 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20   zero to ensure 
24920 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69  future compatibi
24930 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74  lity..**.** ^A t
24940 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73  race callback is
24950 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f   invoked with fo
24960 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61  ur arguments: ca
24970 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e  llback(T,C,P,X).
24980 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d  .** ^The T argum
24990 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ent is one of th
249a0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
249b0 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f  .** constants to
249c0 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 68   indicate why th
249d0 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69  e callback was i
249e0 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nvoked..** ^The 
249f0 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  C argument is a 
24a00 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
24a10 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ext pointer..** 
24a20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75  The P and X argu
24a30 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65  ments are pointe
24a40 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67  rs whose meaning
24a50 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a  s depend on T..*
24a60 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
24a70 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65  _trace_v2() inte
24a80 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65  rface is intende
24a90 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65  d to replace the
24aa0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
24ab0 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74  faces [sqlite3_t
24ac0 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  race()] and [sql
24ad0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c  ite3_profile()],
24ae0 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a   both of which.*
24af0 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64  * are deprecated
24b00 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
24b10 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 63  int sqlite3_trac
24b20 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  e_v2(.  sqlite3*
24b30 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d 61  ,.  unsigned uMa
24b40 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c  sk,.  int(*xCall
24b50 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76  back)(unsigned,v
24b60 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a  oid*,void*,void*
24b70 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 0a  ),.  void *pCtx.
24b80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24b90 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
24ba0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20  ss Callbacks.** 
24bb0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
24bc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
24bd0 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
24be0 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74  ler(D,N,X,P) int
24bf0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
24c00 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  e callback.** fu
24c10 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69  nction X to be i
24c20 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61  nvoked periodica
24c30 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20  lly during long 
24c40 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f  running calls to
24c50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
24c60 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  c()], [sqlite3_s
24c70 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tep()] and [sqli
24c80 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
24c90 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65   for.** database
24ca0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20   connection D.  
24cb0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
24cc0 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
24cd0 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
24ce0 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
24cf0 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
24d00 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ry..**.** ^The p
24d10 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61  arameter P is pa
24d20 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
24d30 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
24d40 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61  er to the .** ca
24d50 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
24d60 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  X.  ^The paramet
24d70 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 72  er N is the appr
24d80 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f  oximate number o
24d90 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
24da0 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
24db0 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
24dc0 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
24dd0 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
24de0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
24df0 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49   callback X.  ^I
24e00 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
24e10 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72   one then the pr
24e20 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65  ogress.** handle
24e30 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  r is disabled..*
24e40 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
24e50 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
24e60 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
24e70 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
24e80 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
24e90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
24ea0 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
24eb0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
24ec0 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
24ed0 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
24ee0 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
24ef0 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
24f00 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
24f10 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
24f20 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
24f30 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
24f40 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
24f50 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
24f60 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
24f70 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
24f80 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
24f90 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
24fa0 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
24fb0 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
24fc0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
24fd0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
24fe0 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
24ff0 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
25000 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
25010 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
25020 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
25030 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
25040 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
25050 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
25060 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
25070 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
25080 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
25090 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
250a0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
250b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
250c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
250d0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
250e0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
250f0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
25100 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
25110 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
25120 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
25130 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
25140 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
25150 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
25160 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
25170 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
25180 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25190 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
251a0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
251b0 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  on.** CONSTRUCTO
251c0 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
251d0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
251e0 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
251f0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
25200 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
25210 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
25220 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
25230 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
25240 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
25250 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
25260 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
25270 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
25280 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
25290 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
252a0 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
252b0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
252c0 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
252d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
252e0 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
252f0 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
25300 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
25310 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
25320 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
25330 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
25340 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
25350 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
25360 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
25370 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
25380 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
25390 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
253a0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
253b0 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
253c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
253d0 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
253e0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
253f0 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
25400 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
25410 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
25420 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
25430 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
25440 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
25450 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
25460 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
25470 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
25480 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
25490 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
254a0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
254b0 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
254c0 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
254d0 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
254e0 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
254f0 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
25500 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
25510 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
25520 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
25530 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c  ult encoding wil
25540 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64  l be UTF-8 for d
25550 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64  atabases created
25560 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65   using.** sqlite
25570 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
25580 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
25590 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
255a0 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61  oding for databa
255b0 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75  ses.** created u
255c0 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  sing sqlite3_ope
255d0 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54  n16() will be UT
255e0 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
255f0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
25600 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
25610 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
25620 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
25630 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
25640 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
25650 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
25660 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
25670 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
25680 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
25690 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
256a0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
256b0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
256c0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
256d0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
256e0 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
256f0 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
25700 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
25710 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
25720 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
25730 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
25740 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
25750 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
25760 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
25770 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
25780 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
25790 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
257a0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
257b0 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
257c0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
257d0 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
257e0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
257f0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
25800 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
25810 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
25820 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
25830 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25840 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
25850 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
25860 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
25870 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
25880 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
25890 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
258a0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
258b0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
258c0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
258d0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
258e0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
258f0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
25900 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
25910 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
25920 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
25930 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
25940 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
25950 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
25960 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
25970 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
25980 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
25990 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
259a0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
259b0 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
259c0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
259d0 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
259e0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
259f0 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
25a00 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
25a10 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
25a20 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
25a30 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
25a40 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
25a50 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
25a60 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
25a70 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
25a80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
25a90 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
25aa0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
25ab0 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
25ac0 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
25ad0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
25ae0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
25af0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
25b00 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
25b10 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
25b20 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
25b30 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
25b40 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
25b50 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
25b60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
25b70 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
25b80 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
25b90 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
25ba0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
25bb0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
25bc0 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
25bd0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
25be0 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
25bf0 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
25c00 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
25c10 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
25c20 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
25c30 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
25c40 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
25c50 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
25c60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
25c70 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
25c80 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
25c90 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
25ca0 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
25cb0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
25cc0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
25cd0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
25ce0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
25cf0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
25d00 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
25d10 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
25d20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
25d30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
25d40 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
25d50 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
25d60 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
25d70 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
25d80 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
25d90 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
25da0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
25db0 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
25dc0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
25dd0 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
25de0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
25df0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
25e00 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
25e10 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
25e20 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
25e30 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
25e40 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
25e50 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
25e60 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
25e70 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
25e80 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
25e90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
25ea0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
25eb0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
25ec0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25ed0 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
25ee0 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
25ef0 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
25f00 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
25f10 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
25f20 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
25f30 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
25f40 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
25f50 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
25f60 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
25f70 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
25f80 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
25f90 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
25fa0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
25fb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25fc0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
25fd0 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
25fe0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
25ff0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
26000 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
26010 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
26020 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
26030 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
26040 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
26050 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
26060 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
26070 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
26080 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
26090 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
260a0 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
260b0 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
260c0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
260d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
260e0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
260f0 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
26100 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
26110 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
26120 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
26130 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
26140 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
26150 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
26160 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
26170 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
26180 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
26190 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
261a0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
261b0 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
261c0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
261d0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
261e0 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
261f0 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
26200 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
26210 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
26220 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
26230 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
26240 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
26250 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
26260 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
26270 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
26280 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
26290 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
262a0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
262b0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
262c0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
262d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
262e0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
262f0 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
26300 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
26310 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
26320 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
26330 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
26340 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
26350 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
26360 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
26370 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
26380 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
26390 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
263a0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
263b0 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
263c0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
263d0 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
263e0 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
263f0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
26400 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
26410 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
26420 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
26430 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
26440 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
26450 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
26460 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
26470 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
26480 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
26490 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
264a0 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
264b0 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
264c0 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
264d0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49 20 66  option..** URI f
264e0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
264f0 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
26500 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
26510 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
26520 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
26530 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
26540 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
26550 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
26560 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
26570 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
26580 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
26590 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
265a0 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
265b0 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
265c0 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
265d0 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
265e0 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
265f0 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
26600 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
26610 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
26620 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
26630 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
26640 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
26650 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
26660 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
26670 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
26680 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
26690 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
266a0 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
266b0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
266c0 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
266d0 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
266e0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
266f0 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
26700 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
26710 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
26720 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
26730 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
26740 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
26750 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
26760 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
26770 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
26780 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
26790 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
267a0 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
267b0 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
267c0 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
267d0 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
267e0 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
267f0 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
26800 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
26810 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
26820 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
26830 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
26840 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69  ath. .** ^(On wi
26850 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74  ndows, the first
26860 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e   component of an
26870 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a   absolute path .
26880 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70  ** is a drive sp
26890 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67  ecification (e.g
268a0 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a  . "C:").)^.**.**
268b0 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72   [[core URI quer
268c0 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a  y parameters]].*
268d0 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70  * The query comp
268e0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d  onent of a URI m
268f0 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d  ay contain param
26900 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69  eters that are i
26910 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69  nterpreted.** ei
26920 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69  ther by SQLite i
26930 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b  tself, or by a [
26940 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53  VFS | custom VFS
26950 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d   implementation]
26960 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  ..** SQLite and 
26970 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46  its built-in [VF
26980 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74  Ses] interpret t
26990 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
269a0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
269b0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
269c0 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
269d0 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
269e0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
269f0 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
26a00 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
26a10 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
26a20 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
26a30 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
26a40 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
26a50 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
26a60 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
26a70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26a80 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
26a90 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
26aa0 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
26ab0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
26ac0 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
26ad0 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
26ae0 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
26af0 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
26b00 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
26b10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26b20 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
26b30 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
26b40 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
26b50 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
26b60 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
26b70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
26b80 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
26b90 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
26ba0 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
26bb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
26bc0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
26bd0 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
26be0 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
26bf0 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
26c00 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
26c10 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c  ther "ro", "rw",
26c20 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f  .**     "rwc", o
26c30 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65  r "memory". Atte
26c40 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
26c50 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
26c60 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e  lue is.**     an
26c70 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
26c80 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
26c90 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
26ca0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
26cb0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
26cc0 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
26cd0 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
26ce0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
26cf0 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
26d00 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
26d10 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
26d20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
26d30 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
26d40 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
26d50 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a  on is set to .**
26d60 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20       "rw", then 
26d70 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
26d80 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
26d90 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63  write (but not c
26da0 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61  reate) .**     a
26db0 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c  ccess, as if SQL
26dc0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
26dd0 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49  TE (but not SQLI
26de0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20  TE_OPEN_CREATE) 
26df0 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e  had .**     been
26e00 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77   set. ^Value "rw
26e10 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  c" is equivalent
26e20 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68   to setting both
26e30 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f   .**     SQLITE_
26e40 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61  OPEN_READWRITE a
26e50 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  nd SQLITE_OPEN_C
26e60 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20  REATE.  ^If the 
26e70 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  mode option is.*
26e80 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65  *     set to "me
26e90 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72  mory" then a pur
26ea0 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  e [in-memory dat
26eb0 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65  abase] that neve
26ec0 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f  r reads.**     o
26ed0 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69  r writes from di
26ee0 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20  sk is used. ^It 
26ef0 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73  is an error to s
26f00 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66  pecify a value f
26f10 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f  or.**     the mo
26f20 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
26f30 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69  t is less restri
26f40 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
26f50 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
26f60 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61      the flags pa
26f70 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72  ssed in the thir
26f80 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
26f90 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26fa0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
26fb0 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
26fc0 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
26fd0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
26fe0 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
26ff0 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
27000 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
27010 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
27020 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
27030 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
27040 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
27050 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
27060 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
27070 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
27080 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
27090 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
270a0 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
270b0 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
270c0 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
270d0 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
270e0 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
270f0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
27100 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
27110 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27120 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
27130 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
27140 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
27150 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
27160 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
27170 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
27180 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74  behavior request
27190 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
271a0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
271b0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
271c0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
271d0 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
271e0 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73  *.**  <li> <b>ps
271f0 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f  ow</b>: ^The pso
27200 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69  w parameter indi
27210 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72  cates whether or
27220 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20   not the.**     
27230 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77  [powersafe overw
27240 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64  rite] property d
27250 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20  oes or does not 
27260 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20  apply to the.** 
27270 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69      storage medi
27280 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64  a on which the d
27290 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73  atabase file res
272a0 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  ides..**.**  <li
272b0 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a  > <b>nolock</b>:
272c0 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72   ^The nolock par
272d0 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
272e0 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65  ean query parame
272f0 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68  ter.**     which
27300 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73   if set disables
27310 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e   file locking in
27320 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61   rollback journa
27330 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a  l modes.  This.*
27340 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20  *     is useful 
27350 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20  for accessing a 
27360 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69  database on a fi
27370 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f  lesystem that do
27380 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75  es not.**     su
27390 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20  pport locking.  
273a0 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61  Caution:  Databa
273b0 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69  se corruption mi
273c0 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77  ght result if tw
273d0 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65  o.**     or more
273e0 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65   processes write
273f0 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
27400 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e  abase and any on
27410 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20  e of those.**   
27420 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73    processes uses
27430 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a   nolock=1..**.**
27440 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61    <li> <b>immuta
27450 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d  ble</b>: ^The im
27460 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65  mutable paramete
27470 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71  r is a boolean q
27480 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61  uery.**     para
27490 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63  meter that indic
274a0 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61  ates that the da
274b0 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73  tabase file is s
274c0 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20  tored on.**     
274d0 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e  read-only media.
274e0 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c    ^When immutabl
274f0 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65  e is set, SQLite
27500 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
27510 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73  e.**     databas
27520 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65  e file cannot be
27530 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62   changed, even b
27540 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68  y a process with
27550 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70   higher.**     p
27560 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f  rivilege, and so
27570 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
27580 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c   opened read-onl
27590 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e  y and all lockin
275a0 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61  g.**     and cha
275b0 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73  nge detection is
275c0 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74   disabled.  Caut
275d0 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65  ion: Setting the
275e0 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20   immutable.**   
275f0 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20    property on a 
27600 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
27610 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20  at does in fact 
27620 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c  change can resul
27630 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f  t.**     in inco
27640 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75  rrect query resu
27650 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  lts and/or [SQLI
27660 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f  TE_CORRUPT] erro
27670 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61  rs..**     See a
27680 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43  lso: [SQLITE_IOC
27690 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a  AP_IMMUTABLE]..*
276a0 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c  *       .** </ul
276b0 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79  >.**.** ^Specify
276c0 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70  ing an unknown p
276d0 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20  arameter in the 
276e0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
276f0 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20  of a URI is not 
27700 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75  an.** error.  Fu
27710 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
27720 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e   SQLite might un
27730 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f  derstand additio
27740 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  nal query.** par
27750 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b  ameters.  See "[
27760 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
27770 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65   with special me
27780 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d  aning to SQLite]
27790 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  " for.** additio
277a0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
277b0 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
277c0 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d  ename examples]]
277d0 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d   <h3>URI filenam
277e0 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a  e examples</h3>.
277f0 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  **.** <table bor
27800 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65  der="1" align=ce
27810 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67  nter cellpadding
27820 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  =5>.** <tr><th> 
27830 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74  URI filenames <t
27840 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74  h> Results.** <t
27850 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
27860 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
27870 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66        Open the f
27880 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e  ile "data.db" in
27890 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
278a0 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  ectory..** <tr><
278b0 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66  td> file:/home/f
278c0 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a  red/data.db<br>.
278d0 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
278e0 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  :///home/fred/da
278f0 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20  ta.db <br> .**  
27900 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c          file://l
27910 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72  ocalhost/home/fr
27920 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
27930 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
27940 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62    Open the datab
27950 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  ase file "/home/
27960 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a  fred/data.db"..*
27970 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
27980 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f  //darkstar/home/
27990 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64  fred/data.db <td
279a0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
279b0 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74  n error. "darkst
279c0 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63  ar" is not a rec
279d0 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74  ognized authorit
279e0 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74  y..** <tr><td st
279f0 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65  yle="white-space
27a00 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20  :nowrap"> .**   
27a10 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43         file:///C
27a20 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e  :/Documents%20an
27a30 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65  d%20Settings/fre
27a40 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64  d/Desktop/data.d
27a50 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69  b.**     <td> Wi
27a60 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e  ndows only: Open
27a70 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
27a80 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65  db" on fred's de
27a90 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a  sktop on drive.*
27aa0 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e  *          C:. N
27ab0 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30  ote that the %20
27ac0 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69   escaping in thi
27ad0 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74  s example is not
27ae0 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20   strictly .**   
27af0 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79         necessary
27b00 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74   - space charact
27b10 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  ers can be used 
27b20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20  literally.**    
27b30 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c        in URI fil
27b40 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c  enames..** <tr><
27b50 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
27b60 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70  ?mode=ro&cache=p
27b70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20  rivate <td> .** 
27b80 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
27b90 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
27ba0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
27bb0 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f  ctory for read-o
27bc0 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20  nly access..**  
27bd0 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65          Regardle
27be0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
27bf0 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68   not shared-cach
27c00 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65  e mode is enable
27c10 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  d by.**         
27c20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20   default, use a 
27c30 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a  private cache..*
27c40 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
27c50 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
27c60 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66  db?vfs=unix-dotf
27c70 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20  ile <td>.**     
27c80 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
27c90 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
27ca0 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65  db". Use the spe
27cb0 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64  cial VFS "unix-d
27cc0 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20  otfile".**      
27cd0 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f      that uses do
27ce0 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65  t-files in place
27cf0 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f   of posix adviso
27d00 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c  ry locking..** <
27d10 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
27d20 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e  a.db?mode=readon
27d30 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  ly <td> .**     
27d40 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
27d50 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74  readonly" is not
27d60 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20   a valid option 
27d70 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70  for the "mode" p
27d80 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74  arameter..** </t
27d90 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49  able>.**.** ^URI
27da0 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63   hexadecimal esc
27db0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25  ape sequences (%
27dc0 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65  HH) are supporte
27dd0 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74  d within the pat
27de0 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63  h and.** query c
27df0 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55  omponents of a U
27e00 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61  RI. A hexadecima
27e10 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
27e20 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a  e consists of a.
27e30 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20  ** percent sign 
27e40 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64  - "%" - followed
27e50 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20   by exactly two 
27e60 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69  hexadecimal digi
27e70 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e  ts .** specifyin
27e80 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65  g an octet value
27e90 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61  . ^Before the pa
27ea0 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70  th or query comp
27eb0 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55  onents of a.** U
27ec0 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20  RI filename are 
27ed0 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65  interpreted, the
27ee0 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73  y are encoded us
27ef0 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c  ing UTF-8 and al
27f00 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61  l .** hexadecima
27f10 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
27f20 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  es replaced by a
27f30 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e   single byte con
27f40 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
27f50 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74  orresponding oct
27f60 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63  et. If this proc
27f70 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e  ess generates an
27f80 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65   invalid UTF-8 e
27f90 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  ncoding,.** the 
27fa0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
27fb0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  fined..**.** <b>
27fc0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
27fd0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
27fe0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
27ff0 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
28000 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
28010 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
28020 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
28030 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
28040 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
28050 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
28060 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
28070 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
28080 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
28090 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
280a0 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
280b0 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
280c0 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
280d0 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
280e0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
280f0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
28100 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
28110 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
28120 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
28130 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
28140 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
28150 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
28160 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  lling sqlite3_op
28170 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
28180 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65  open_v2().  Othe
28190 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
281a0 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
281b0 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
281c0 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
281d0 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a  es may fail..**.
281e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
281f0 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
28200 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tory].*/.SQLITE_
28210 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
28220 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68  open(.  const ch
28230 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
28240 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
28250 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
28260 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
28270 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
28280 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
28290 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  le */.);.SQLITE_
282a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
282b0 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20  open16(.  const 
282c0 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  void *filename, 
282d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
282e0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20  lename (UTF-16) 
282f0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
28300 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
28310 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
28320 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49  andle */.);.SQLI
28330 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
28340 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f  e3_open_v2(.  co
28350 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61  nst char *filena
28360 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
28370 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
28380 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  8) */.  sqlite3 
28390 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20  **ppDb,         
283a0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
283b0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e  b handle */.  in
283c0 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20  t flags,        
283d0 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a        /* Flags *
283e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
283f0 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e  zVfs        /* N
28400 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c  ame of VFS modul
28410 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a  e to use */.);..
28420 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28430 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f  Obtain Values Fo
28440 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73  r URI Parameters
28450 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
28460 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65   utility routine
28470 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53  s, useful to VFS
28480 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
28490 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20  , that check.** 
284a0 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61  to see if a data
284b0 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20  base file was a 
284c0 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  URI that contain
284d0 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75  ed a specific qu
284e0 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ery .** paramete
284f0 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74  r, and if so obt
28500 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  ains the value o
28510 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72  f that query par
28520 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
28530 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61   F is the databa
28540 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e  se filename poin
28550 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ter passed into 
28560 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68  the xOpen() meth
28570 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20  od of .** a VFS 
28580 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
28590 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61  hen the flags pa
285a0 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
285b0 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a  () has one or .*
285c0 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53  * more of the [S
285d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
285e0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
285f0 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65  MAIN_DB] bits se
28600 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68  t and.** P is th
28610 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75  e name of the qu
28620 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ery parameter, t
28630 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  hen.** sqlite3_u
28640 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
28650 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  ) returns the va
28660 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20  lue of the P.** 
28670 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20  parameter if it 
28680 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c  exists or a NULL
28690 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f   pointer if P do
286a0 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73  es not appear as
286b0 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   a .** query par
286c0 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66  ameter on F.  If
286d0 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61   P is a query pa
286e0 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20  rameter of F.** 
286f0 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20  has no explicit 
28700 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69  value, then sqli
28710 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
28720 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a  r(F,P) returns.*
28730 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
28740 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
28750 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
28760 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
28770 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73  P,B) routine ass
28780 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61  umes that P is a
28790 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61   boolean.** para
287a0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
287b0 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61  s true (1) or fa
287c0 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e  lse (0) accordin
287d0 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a  g to the value.*
287e0 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c  * of P.  The sql
287f0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
28800 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
28810 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
28820 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65   if the.** value
28830 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65   of query parame
28840 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
28850 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f  "yes", "true", o
28860 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a  r "on" in any.**
28870 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20   case or if the 
28880 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
28890 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d  h a non-zero num
288a0 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71  ber.  The .** sq
288b0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
288c0 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
288d0 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  s returns false 
288e0 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65  (0) if the value
288f0 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72   of.** query par
28900 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
28910 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22  of "no", "false"
28920 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e  , or "off" in an
28930 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20  y case or.** if 
28940 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
28950 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20   with a numeric 
28960 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e  zero.  If P is n
28970 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61  ot a query.** pa
28980 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20  rameter on F or 
28990 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  if the value of 
289a0 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61  P is does not ma
289b0 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a  tch any of the.*
289c0 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71  * above, then sq
289d0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
289e0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
289f0 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54   (B!=0)..**.** T
28a00 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  he sqlite3_uri_i
28a10 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74  nt64(F,P,D) rout
28a20 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65  ine converts the
28a30 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f   value of P into
28a40 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67   a.** 64-bit sig
28a50 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
28a60 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74  returns that int
28a70 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20  eger, or D if P 
28a80 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73  does not.** exis
28a90 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65  t.  If the value
28aa0 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69   of P is somethi
28ab0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e  ng other than an
28ac0 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a   integer, then.*
28ad0 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e  * zero is return
28ae0 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20  ed..** .** If F 
28af0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
28b00 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
28b10 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
28b20 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  P) returns NULL 
28b30 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  and.** sqlite3_u
28b40 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
28b50 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66  ) returns B.  If
28b60 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c   F is not a NULL
28b70 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20   pointer and.** 
28b80 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
28b90 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  e file pathname 
28ba0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c  pointer that SQL
28bb0 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ite passed into 
28bc0 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53  the xOpen.** VFS
28bd0 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
28be0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
28bf0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e  is routine is un
28c00 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
28c10 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61  ably.** undesira
28c20 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ble..*/.SQLITE_A
28c30 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
28c40 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
28c50 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
28c60 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
28c70 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
28c80 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
28c90 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
28ca0 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
28cb0 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
28cc0 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
28cd0 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45  Default);.SQLITE
28ce0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
28cf0 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  64 sqlite3_uri_i
28d00 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a  nt64(const char*
28d10 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
28d20 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
28d30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
28d40 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
28d50 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54   Messages.** MET
28d60 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
28d70 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
28d80 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a  recent sqlite3_*
28d90 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69   API call associ
28da0 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64  ated with .** [d
28db0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28dc0 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68  on] D failed, th
28dd0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  en the sqlite3_e
28de0 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66  rrcode(D) interf
28df0 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ace.** returns t
28e00 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
28e10 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  lt code] or [ext
28e20 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
28e30 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41  e] for that.** A
28e40 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74  PI call..** If t
28e50 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
28e60 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63  PI call was succ
28e70 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20  essful,.** then 
28e80 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
28e90 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72   from sqlite3_er
28ea0 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
28eb0 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ined..** ^The sq
28ec0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
28ed0 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
28ee0 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
28ef0 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
28f00 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
28f10 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
28f20 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
28f30 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
28f40 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
28f50 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
28f60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28f70 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
28f80 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
28f90 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
28fa0 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
28fb0 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
28fc0 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
28fd0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
28fe0 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
28ff0 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
29000 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
29010 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
29020 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
29030 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
29040 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
29050 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
29060 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
29070 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
29080 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
29090 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
290a0 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
290b0 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
290c0 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
290d0 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
290e0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
290f0 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
29100 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
29110 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
29120 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
29130 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
29140 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
29150 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
29160 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
29170 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
29180 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
29190 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
291a0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
291b0 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
291c0 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
291d0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
291e0 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
291f0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
29200 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
29210 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
29220 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
29230 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
29240 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
29250 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
29260 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
29270 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
29280 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
29290 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
292a0 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
292b0 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
292c0 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
292d0 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
292e0 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
292f0 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
29300 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
29310 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
29320 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
29330 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
29340 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
29350 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
29360 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
29370 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
29380 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
29390 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
293a0 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
293b0 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
293c0 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
293d0 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
293e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
293f0 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
29400 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
29410 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
29420 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
29430 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
29440 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
29450 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
29460 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
29470 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
29480 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
29490 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
294a0 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
294b0 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
294c0 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
294d0 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
294e0 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
294f0 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
29500 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
29510 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
29520 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
29530 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c  qlite3 *db);.SQL
29540 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
29550 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
29560 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
29570 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
29580 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
29590 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33  3_errmsg(sqlite3
295a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
295b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
295c0 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
295d0 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
295e0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
295f0 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74  lite3_errstr(int
29600 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29610 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61  EF: Prepared Sta
29620 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
29630 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
29640 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
29650 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
29660 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
29670 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
29680 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
29690 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
296a0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a  tatement that.**
296b0 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c   has been compil
296c0 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66  ed into binary f
296d0 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79  orm and is ready
296e0 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
296f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66  ..**.** Think of
29700 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
29710 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74  ent as a separat
29720 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72  e computer progr
29730 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67  am.  The.** orig
29740 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73  inal SQL text is
29750 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41   source code.  A
29760 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29770 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69  ent object .** i
29780 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f  s the compiled o
29790 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c  bject code.  All
297a0 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e   SQL must be con
297b0 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a  verted into a.**
297c0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
297d0 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61  ent before it ca
297e0 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20  n be run..**.** 
297f0 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f  The life-cycle o
29800 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  f a prepared sta
29810 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
29820 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20  ually goes like 
29830 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
29840 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
29850 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
29860 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73  tement object us
29870 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
29880 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c  pare_v2()]..** <
29890 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
298a0 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20  to [parameters] 
298b0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
298c0 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
298d0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
298e0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
298f0 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
29900 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
29910 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
29920 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
29930 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
29940 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
29950 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
29960 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
29970 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
29980 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
29990 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
299a0 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
299b0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
299c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
299d0 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74  ]..** </ol>.*/.t
299e0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
299f0 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
29a00 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
29a10 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
29a20 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54  me Limits.** MET
29a30 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
29a40 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
29a50 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
29a60 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
29a70 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
29a80 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
29a90 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
29aa0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
29ab0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
29ac0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
29ad0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29ae0 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
29af0 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
29b00 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
29b10 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
29b20 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
29b30 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
29b40 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
29b50 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
29b60 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
29b70 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
29b80 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
29b90 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
29ba0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
29bb0 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
29bc0 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
29bd0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
29be0 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
29bf0 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
29c00 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
29c10 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
29c20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
29c30 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
29c40 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
29c50 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
29c60 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
29c70 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
29c80 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
29c90 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
29ca0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
29cb0 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
29cc0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
29cd0 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
29ce0 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
29cf0 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
29d00 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
29d10 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
29d20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
29d30 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
29d40 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
29d50 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
29d60 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
29d70 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
29d80 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
29d90 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
29da0 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
29db0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
29dc0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
29dd0 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
29de0 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
29df0 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
29e00 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
29e10 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
29e20 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
29e30 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
29e40 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
29e50 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
29e60 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
29e70 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
29e80 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
29e90 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
29ea0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
29eb0 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
29ec0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
29ed0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
29ee0 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
29ef0 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
29f00 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
29f10 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
29f20 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
29f30 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
29f40 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
29f50 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
29f60 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
29f70 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
29f80 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
29f90 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
29fa0 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
29fb0 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
29fc0 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
29fd0 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
29fe0 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
29ff0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
2a000 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
2a010 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
2a020 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
2a030 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
2a040 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
2a050 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
2a060 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
2a070 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
2a080 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
2a090 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
2a0a0 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
2a0b0 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
2a0c0 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
2a0d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
2a0e0 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
2a0f0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
2a100 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
2a110 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
2a120 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
2a130 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
2a140 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
2a150 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
2a160 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
2a170 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
2a180 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
2a190 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
2a1a0 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
2a1b0 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
2a1c0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
2a1d0 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  eases..*/.SQLITE
2a1e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2a1f0 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c  _limit(sqlite3*,
2a200 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77   int id, int new
2a210 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Val);../*.** CAP
2a220 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
2a230 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73  Limit Categories
2a240 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c  .** KEYWORDS: {l
2a250 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b  imit category} {
2a260 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  *limit categorie
2a270 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  s}.**.** These c
2a280 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
2a290 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61  various performa
2a2a0 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68  nce limits.** th
2a2b0 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65  at can be lowere
2a2c0 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73  d at run-time us
2a2d0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
2a2e0 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79  it()]..** The sy
2a2f0 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65  nopsis of the me
2a300 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61  anings of the va
2a310 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20  rious limits is 
2a320 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20  shown below..** 
2a330 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  Additional infor
2a340 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61  mation is availa
2a350 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c  ble at [limits |
2a360 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74   Limits in SQLit
2a370 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  e]..**.** <dl>.*
2a380 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2a390 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
2a3a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2a3b0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
2a3c0 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
2a3d0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
2a3e0 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
2a3f0 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64  row, in bytes.<d
2a400 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a410 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
2a420 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
2a430 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
2a440 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
2a450 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
2a460 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
2a470 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
2a480 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2a490 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
2a4a0 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51  OLUMN]] ^(<dt>SQ
2a4b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
2a4c0 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  N</dt>.** <dd>Th
2a4d0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2a4e0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2a4f0 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f   table definitio
2a500 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72  n or in the.** r
2a510 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
2a520 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d  SELECT] or the m
2a530 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
2a540 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69   columns in an i
2a550 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e  ndex.** or in an
2a560 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f   ORDER BY or GRO
2a570 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64  UP BY clause.</d
2a580 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2a590 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
2a5a0 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
2a5b0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
2a5c0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
2a5d0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
2a5e0 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20  th of the parse 
2a5f0 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72  tree on any expr
2a600 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  ession.</dd>)^.*
2a610 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2a620 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
2a630 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ECT]] ^(<dt>SQLI
2a640 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
2a650 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
2a660 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a670 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
2a680 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
2a690 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
2a6a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2a6b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
2a6c0 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  E_OP]] ^(<dt>SQL
2a6d0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2a6e0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
2a6f0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2a700 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
2a710 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
2a720 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
2a730 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
2a740 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
2a750 65 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65  ent.  If [sqlite
2a760 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2a770 6f 72 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61  or.** the equiva
2a780 6c 65 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c  lent tries to al
2a790 6c 6f 63 61 74 65 20 73 70 61 63 65 20 66 6f 72  locate space for
2a7a0 20 6d 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20   more than this 
2a7b0 6d 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20  many opcodes.** 
2a7c0 69 6e 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70  in a single prep
2a7d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20  ared statement, 
2a7e0 61 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  an SQLITE_NOMEM 
2a7f0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
2a800 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
2a810 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  [[SQLITE_LIMIT_F
2a820 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28  UNCTION_ARG]] ^(
2a830 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a840 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
2a850 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2a860 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2a870 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
2a880 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
2a890 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2a8a0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20  IMIT_ATTACHED]] 
2a8b0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a8c0 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
2a8d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2a8e0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
2a8f0 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
2a900 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
2a910 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
2a920 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
2a930 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a  TTERN_LENGTH]].*
2a940 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
2a950 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
2a960 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
2a970 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a980 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
2a990 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
2a9a0 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
2a9b0 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
2a9c0 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tors.</dd>)^.**.
2a9d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a9e0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2a9f0 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  R]].** ^(<dt>SQL
2aa00 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2aa10 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
2aa20 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2aa30 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
2aa40 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
2aa50 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
2aa60 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  ement.)^.**.** [
2aa70 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  [SQLITE_LIMIT_TR
2aa80 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28  IGGER_DEPTH]] ^(
2aa90 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2aaa0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
2aab0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2aac0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
2aad0 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
2aae0 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
2aaf0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2ab00 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
2ab10 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  DS]] ^(<dt>SQLIT
2ab20 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
2ab30 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  HREADS</dt>.** <
2ab40 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2ab50 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61  umber of auxilia
2ab60 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64  ry worker thread
2ab70 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a  s that a single.
2ab80 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2ab90 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72  tement] may star
2aba0 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  t.</dd>)^.** </d
2abb0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
2abc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2abd0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
2abe0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
2abf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
2ac00 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
2ac10 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
2ac20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
2ac30 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
2ac40 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
2ac50 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
2ac60 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
2ac70 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
2ac80 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
2ac90 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
2aca0 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
2acb0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2acc0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
2acd0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
2ace0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2acf0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
2ad00 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
2ad10 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2ad20 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
2ad30 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
2ad40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2ad50 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
2ad60 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
2ad70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2ad80 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2ad90 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
2ada0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2adb0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
2adc0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
2add0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2ade0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
2adf0 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31  EADS           1
2ae00 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  1../*.** CAPI3RE
2ae10 46 3a 20 50 72 65 70 61 72 65 20 46 6c 61 67 73  F: Prepare Flags
2ae20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2ae30 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
2ae40 72 69 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74  rious flags that
2ae50 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 69   can be passed i
2ae60 6e 74 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67  nto.** "prepFlag
2ae70 73 22 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  s" parameter of 
2ae80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
2ae90 70 61 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a  pare_v3()] and.*
2aea0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2aeb0 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 74 65 72  re16_v3()] inter
2aec0 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  faces..**.** New
2aed0 20 66 6c 61 67 73 20 6d 61 79 20 62 65 20 61 64   flags may be ad
2aee0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
2aef0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
2af00 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
2af10 5b 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  [[SQLITE_PREPARE
2af20 5f 50 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28  _PERSISTENT]] ^(
2af30 3c 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41  <dt>SQLITE_PREPA
2af40 52 45 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f 64  RE_PERSISTENT</d
2af50 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51  t>.** <dd>The SQ
2af60 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52  LITE_PREPARE_PER
2af70 53 49 53 54 45 4e 54 20 66 6c 61 67 20 69 73 20  SISTENT flag is 
2af80 61 20 68 69 6e 74 20 74 6f 20 74 68 65 20 71 75  a hint to the qu
2af90 65 72 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74  ery planner.** t
2afa0 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64  hat the prepared
2afb0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2afc0 62 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  be retained for 
2afd0 61 20 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a  a long time and.
2afe0 2a 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 75 73  ** probably reus
2aff0 65 64 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e  ed many times.)^
2b000 20 5e 57 69 74 68 6f 75 74 20 74 68 69 73 20 66   ^Without this f
2b010 6c 61 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  lag, [sqlite3_pr
2b020 65 70 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61  epare_v3()].** a
2b030 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2b040 61 72 65 31 36 5f 76 33 28 29 5d 20 61 73 73 75  are16_v3()] assu
2b050 6d 65 20 74 68 61 74 20 74 68 65 20 70 72 65 70  me that the prep
2b060 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77  ared statement w
2b070 69 6c 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64 20  ill .** be used 
2b080 6a 75 73 74 20 6f 6e 63 65 20 6f 72 20 61 74 20  just once or at 
2b090 6d 6f 73 74 20 61 20 66 65 77 20 74 69 6d 65 73  most a few times
2b0a0 20 61 6e 64 20 74 68 65 6e 20 64 65 73 74 72 6f   and then destro
2b0b0 79 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  yed using.** [sq
2b0c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2b0d0 5d 20 72 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f  ] relatively soo
2b0e0 6e 2e 20 54 68 65 20 63 75 72 72 65 6e 74 20 69  n. The current i
2b0f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63  mplementation ac
2b100 74 73 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69  ts.** on this hi
2b110 6e 74 20 62 79 20 61 76 6f 69 64 69 6e 67 20 74  nt by avoiding t
2b120 68 65 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61  he use of [looka
2b130 73 69 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20  side memory] so 
2b140 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70  as not to.** dep
2b150 6c 65 74 65 20 74 68 65 20 6c 69 6d 69 74 65 64  lete the limited
2b160 20 73 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73   store of lookas
2b170 69 64 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75  ide memory. Futu
2b180 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a  re versions of.*
2b190 2a 20 53 51 4c 69 74 65 20 6d 61 79 20 61 63 74  * SQLite may act
2b1a0 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 64 69   on this hint di
2b1b0 66 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f  fferently..** </
2b1c0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
2b1d0 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45  QLITE_PREPARE_PE
2b1e0 52 53 49 53 54 45 4e 54 20 20 20 20 20 20 20 20  RSISTENT        
2b1f0 20 20 20 20 20 20 30 78 30 31 0a 0a 2f 2a 0a 2a        0x01../*.*
2b200 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
2b210 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
2b220 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
2b230 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
2b240 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20  nt compiler}.** 
2b250 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
2b260 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
2b270 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2b280 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
2b290 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2b2a0 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
2b2b0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
2b2c0 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
2b2d0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
2b2e0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2b2f0 73 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65 72  s.  Or, in other
2b300 20 77 6f 72 64 73 2c 20 74 68 65 73 65 20 72 6f   words, these ro
2b310 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63 6f  utines.** are co
2b320 6e 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 74  nstructors for t
2b330 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2b340 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a  tement] object..
2b350 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66 65 72  **.** The prefer
2b360 72 65 64 20 72 6f 75 74 69 6e 65 20 74 6f 20 75  red routine to u
2b370 73 65 20 69 73 20 5b 73 71 6c 69 74 65 33 5f 70  se is [sqlite3_p
2b380 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 20 20 54  repare_v2()].  T
2b390 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
2b3a0 72 65 70 61 72 65 28 29 5d 20 69 6e 74 65 72 66  repare()] interf
2b3b0 61 63 65 20 69 73 20 6c 65 67 61 63 79 20 61 6e  ace is legacy an
2b3c0 64 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69  d should be avoi
2b3d0 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ded..** [sqlite3
2b3e0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 68  _prepare_v3()] h
2b3f0 61 73 20 61 6e 20 65 78 74 72 61 20 22 70 72 65  as an extra "pre
2b400 70 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20 74  pFlags" option t
2b410 68 61 74 20 69 73 20 75 73 65 64 0a 2a 2a 20 66  hat is used.** f
2b420 6f 72 20 73 70 65 63 69 61 6c 20 70 75 72 70 6f  or special purpo
2b430 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ses..**.** The u
2b440 73 65 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20  se of the UTF-8 
2b450 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 70 72  interfaces is pr
2b460 65 66 65 72 72 65 64 2c 20 61 73 20 53 51 4c 69  eferred, as SQLi
2b470 74 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  te currently.** 
2b480 64 6f 65 73 20 61 6c 6c 20 70 61 72 73 69 6e 67  does all parsing
2b490 20 75 73 69 6e 67 20 55 54 46 2d 38 2e 20 20 54   using UTF-8.  T
2b4a0 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66  he UTF-16 interf
2b4b0 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
2b4c0 64 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65 6e  d.** as a conven
2b4d0 69 65 6e 63 65 2e 20 20 54 68 65 20 55 54 46 2d  ience.  The UTF-
2b4e0 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f  16 interfaces wo
2b4f0 72 6b 20 62 79 20 63 6f 6e 76 65 72 74 69 6e 67  rk by converting
2b500 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74 65   the.** input te
2b510 78 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20 74  xt into UTF-8, t
2b520 68 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hen invoking the
2b530 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 55   corresponding U
2b540 54 46 2d 38 20 69 6e 74 65 72 66 61 63 65 2e 0a  TF-8 interface..
2b550 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2b560 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
2b570 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
2b580 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
2b590 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
2b5a0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
2b5b0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2b5c0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2b5d0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
2b5e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
2b5f0 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
2b600 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2b610 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
2b620 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
2b630 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2b640 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
2b650 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
2b660 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
2b670 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
2b680 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
2b690 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
2b6a0 33 5f 70 72 65 70 61 72 65 28 29 2c 20 73 71 6c  3_prepare(), sql
2b6b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2b6c0 29 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ),.** and sqlite
2b6d0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 0a 2a  3_prepare_v3().*
2b6e0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
2b6f0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
2b700 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 2c  te3_prepare16(),
2b710 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b720 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  16_v2(),.** and 
2b730 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b740 36 5f 76 33 28 29 20 75 73 65 20 55 54 46 2d 31  6_v3() use UTF-1
2b750 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
2b760 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
2b770 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2b780 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
2b790 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
2b7a0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2b7b0 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
2b7c0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69  positive, then i
2b7d0 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  t is the.** numb
2b7e0 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64  er of bytes read
2b7f0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66   from zSql.  ^If
2b800 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20   nByte is zero, 
2b810 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64  then no prepared
2b820 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73  .** statement is
2b830 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49   generated..** I
2b840 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
2b850 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ws that the supp
2b860 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
2b870 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
2b880 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20  hen.** there is 
2b890 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61  a small performa
2b8a0 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
2b8b0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
2b8c0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
2b8d0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
2b8e0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2b8f0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
2b900 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
2b910 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
2b920 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nator..**.** ^If
2b930 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
2b940 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
2b950 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
2b960 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
2b970 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
2b980 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
2b990 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
2b9a0 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
2b9b0 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
2b9c0 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
2b9d0 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
2b9e0 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
2b9f0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
2ba00 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
2ba10 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
2ba20 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
2ba30 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
2ba40 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
2ba50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ba60 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
2ba70 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
2ba80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2ba90 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
2baa0 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
2bab0 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
2bac0 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
2bad0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
2bae0 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
2baf0 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
2bb00 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
2bb10 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
2bb20 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
2bb30 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
2bb40 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
2bb50 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
2bb60 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
2bb70 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
2bb80 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
2bb90 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
2bba0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
2bbb0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2bbc0 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
2bbd0 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
2bbe0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
2bbf0 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
2bc00 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
2bc10 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
2bc20 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
2bc30 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
2bc40 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2bc50 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2bc60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
2bc70 70 61 72 65 5f 76 32 28 29 2c 20 73 71 6c 69 74  pare_v2(), sqlit
2bc80 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 2c  e3_prepare_v3(),
2bc90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2bca0 31 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20  16_v2(),.** and 
2bcb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2bcc0 36 5f 76 33 28 29 20 69 6e 74 65 72 66 61 63 65  6_v3() interface
2bcd0 73 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64 65  s are recommende
2bce0 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
2bcf0 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f  ograms..** The o
2bd00 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
2bd10 28 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  (sqlite3_prepare
2bd20 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
2bd30 72 65 70 61 72 65 31 36 28 29 29 0a 2a 2a 20 61  repare16()).** a
2bd40 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
2bd50 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
2bd60 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
2bd70 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
2bd80 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
2bd90 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65  e "vX" interface
2bda0 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
2bdb0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
2bdc0 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
2bdd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2bde0 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
2bdf0 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
2be00 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
2be10 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
2be20 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
2be30 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
2be40 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
2be50 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
2be60 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
2be70 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
2be80 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
2be90 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
2bea0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
2beb0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
2bec0 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
2bed0 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
2bee0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
2bef0 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
2bf00 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
2bf10 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
2bf20 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
2bf30 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73  run it again. As
2bf40 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45   many as [SQLITE
2bf50 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52  _MAX_SCHEMA_RETR
2bf60 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69  Y].** retries wi
2bf70 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20  ll occur before 
2bf80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67  sqlite3_step() g
2bf90 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75  ives up and retu
2bfa0 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  rns an error..**
2bfb0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
2bfc0 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
2bfd0 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
2bfe0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
2bff0 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
2c000 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
2c010 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
2c020 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
2c030 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
2c040 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
2c050 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
2c060 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
2c070 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
2c080 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
2c090 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
2c0a0 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
2c0b0 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
2c0c0 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
2c0d0 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
2c0e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
2c0f0 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
2c100 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
2c110 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
2c120 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
2c130 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
2c140 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
2c150 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
2c160 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
2c170 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
2c180 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
2c190 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2c1a0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2c1b0 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
2c1c0 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
2c1d0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
2c1e0 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
2c1f0 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
2c200 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
2c210 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
2c220 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
2c230 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
2c240 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
2c250 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
2c260 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
2c270 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
2c280 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
2c290 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
2c2a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c2b0 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
2c2c0 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
2c2d0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
2c2e0 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
2c2f0 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
2c300 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
2c310 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
2c320 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
2c330 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
2c340 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2c350 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
2c360 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
2c370 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
2c380 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
2c390 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
2c3a0 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
2c3b0 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
2c3c0 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
2c3d0 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
2c3e0 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
2c3f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
2c400 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
2c410 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
2c420 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c   enabled..** </l
2c430 69 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 6c  i>.**.** <p>^sql
2c440 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2c450 29 20 64 69 66 66 65 72 73 20 66 72 6f 6d 20 73  ) differs from s
2c460 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c470 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68 61 76 69  2() only in havi
2c480 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74 72 61 20  ng.** the extra 
2c490 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65  prepFlags parame
2c4a0 74 65 72 2c 20 77 68 69 63 68 20 69 73 20 61 20  ter, which is a 
2c4b0 62 69 74 20 61 72 72 61 79 20 63 6f 6e 73 69 73  bit array consis
2c4c0 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20 6f 72 0a  ting of zero or.
2c4d0 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
2c4e0 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2c4f0 45 52 53 49 53 54 45 4e 54 7c 53 51 4c 49 54 45  ERSISTENT|SQLITE
2c500 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66 6c 61 67  _PREPARE_*] flag
2c510 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  s.  ^The.** sqli
2c520 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2c530 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
2c540 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
2c550 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e as.** sqlite3_
2c560 70 72 65 70 61 72 65 5f 76 33 28 29 20 77 69 74  prepare_v3() wit
2c570 68 20 61 20 7a 65 72 6f 20 70 72 65 70 46 6c 61  h a zero prepFla
2c580 67 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  gs parameter..**
2c590 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ol>.*/.SQLITE
2c5a0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2c5b0 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
2c5c0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2c5d0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2c5e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2c5f0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
2c600 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2c610 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
2c620 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2c630 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2c640 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2c650 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2c660 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
2c670 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
2c680 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
2c690 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
2c6a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
2c6b0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
2c6c0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
2c6d0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
2c6e0 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
2c6f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
2c700 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
2c710 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2c720 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2c730 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2c740 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2c750 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2c760 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2c770 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2c780 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2c790 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2c7a0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2c7b0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2c7c0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2c7d0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2c7e0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2c7f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2c800 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2c810 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2c820 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2c830 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
2c840 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2c850 70 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71  prepare_v3(.  sq
2c860 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2c870 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2c880 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2c890 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2c8a0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2c8b0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2c8c0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2c8d0 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2c8e0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2c8f0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2c900 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69  bytes. */.  unsi
2c910 67 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61  gned int prepFla
2c920 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d  gs, /* Zero or m
2c930 6f 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41  ore SQLITE_PREPA
2c940 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73  RE_ flags */.  s
2c950 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2c960 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2c970 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2c980 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2c990 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2c9a0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2c9b0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2c9c0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
2c9d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2c9e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
2c9f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2ca00 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2ca10 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2ca20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2ca30 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2ca40 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2ca50 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2ca60 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2ca70 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2ca80 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2ca90 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2caa0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2cab0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2cac0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2cad0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2cae0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2caf0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2cb00 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2cb10 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
2cb20 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2cb30 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2cb40 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2cb50 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2cb60 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2cb70 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2cb80 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2cb90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2cba0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2cbb0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2cbc0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2cbd0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2cbe0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2cbf0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2cc00 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2cc10 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2cc20 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2cc30 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2cc40 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2cc50 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2cc60 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2cc70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2cc80 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2cc90 31 36 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33  16_v3(.  sqlite3
2cca0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2ccb0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2ccc0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2ccd0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2cce0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2ccf0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2cd00 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2cd10 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2cd20 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2cd30 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2cd40 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64  s. */.  unsigned
2cd50 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20   int prepFlags, 
2cd60 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  /* Zero or more 
2cd70 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20  SQLITE_PREPARE_ 
2cd80 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74  flags */.  sqlit
2cd90 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2cda0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2cdb0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2cdc0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
2cdd0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2cde0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2cdf0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2ce00 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ql */.);../*.** 
2ce10 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65  CAPI3REF: Retrie
2ce20 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53  ving Statement S
2ce30 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  QL.** METHOD: sq
2ce40 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2ce50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71   ^The sqlite3_sq
2ce60 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  l(P) interface r
2ce70 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2ce80 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68   to a copy of th
2ce90 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74  e UTF-8.** SQL t
2cea0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
2ceb0 74 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  te [prepared sta
2cec0 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77  tement] P if P w
2ced0 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  as.** created by
2cee0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2cef0 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
2cf00 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
2cf10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2cf20 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72  pare16_v2()], or
2cf30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2cf40 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54  e16_v3()]..** ^T
2cf50 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  he sqlite3_expan
2cf60 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72  ded_sql(P) inter
2cf70 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2cf80 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d  ointer to a UTF-
2cf90 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  8.** string cont
2cfa0 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74  aining the SQL t
2cfb0 65 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20  ext of prepared 
2cfc0 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68  statement P with
2cfd0 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d  .** [bound param
2cfe0 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e  eters] expanded.
2cff0 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
2d000 6d 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61  mple, if a prepa
2d010 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
2d020 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74   created using t
2d030 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22  he SQL.** text "
2d040 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a  SELECT $abc,:xyz
2d050 22 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74  " and if paramet
2d060 65 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64  er $abc is bound
2d070 20 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35   to integer 2345
2d080 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65  .** and paramete
2d090 72 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e  r :xyz is unboun
2d0a0 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
2d0b0 73 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72  sql() will retur
2d0c0 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  n.** the origina
2d0d0 6c 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43  l string, "SELEC
2d0e0 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74  T $abc,:xyz" but
2d0f0 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2d100 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20  d_sql().** will 
2d110 72 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32  return "SELECT 2
2d120 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a  345,NULL".)^.**.
2d130 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d140 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69  expanded_sql() i
2d150 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d160 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69   NULL if insuffi
2d170 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20  cient memory.** 
2d180 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20  is available to 
2d190 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c  hold the result,
2d1a0 20 6f 72 20 69 66 20 74 68 65 20 72 65 73 75 6c   or if the resul
2d1b0 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74  t would exceed t
2d1c0 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75  he.** the maximu
2d1d0 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20  m string length 
2d1e0 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
2d1f0 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  e [SQLITE_LIMIT_
2d200 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LENGTH]..**.** ^
2d210 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
2d220 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
2d230 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2d240 6e 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a  n limits the siz
2d250 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61  e of.** bound pa
2d260 72 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f  rameter expansio
2d270 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ns.  ^The [SQLIT
2d280 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f  E_OMIT_TRACE] co
2d290 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
2d2a0 74 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69  tion causes sqli
2d2b0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2d2c0 28 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74  () to always ret
2d2d0 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20  urn NULL..**.** 
2d2e0 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75  ^The string retu
2d2f0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2d300 73 71 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65  sql(P) is manage
2d310 64 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20  d by SQLite and 
2d320 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
2d330 6c 6c 79 20 66 72 65 65 64 20 77 68 65 6e 20 74  lly freed when t
2d340 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2d350 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
2d360 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69  ed..** ^The stri
2d370 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ng returned by s
2d380 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2d390 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f  sql(P), on the o
2d3a0 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73  ther hand,.** is
2d3b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2d3c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2d3d0 5d 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72  ] and must be fr
2d3e0 65 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ee by the applic
2d3f0 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73  ation.** by pass
2d400 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
2d410 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 53  e3_free()]..*/.S
2d420 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2d430 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
2d440 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
2d450 70 53 74 6d 74 29 3b 0a 53 51 4c 49 54 45 5f 41  pStmt);.SQLITE_A
2d460 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
2d470 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71  _expanded_sql(sq
2d480 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2d490 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2d4a0 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
2d4b0 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
2d4c0 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
2d4d0 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44  tabase.** METHOD
2d4e0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2d4f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d500 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2d510 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
2d520 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
2d530 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
2d540 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
2d550 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d560 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
2d570 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
2d580 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2d590 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2d5a0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2d5b0 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
2d5c0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2d5d0 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
2d5e0 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
2d5f0 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
2d600 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
2d610 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
2d620 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
2d630 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
2d640 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
2d650 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
2d660 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
2d670 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
2d680 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
2d690 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
2d6a0 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
2d6b0 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2d6c0 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
2d6d0 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
2d6e0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2d6f0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
2d700 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
2d710 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
2d720 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
2d730 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
2d740 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
2d750 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
2d760 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
2d770 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
2d780 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
2d790 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
2d7a0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
2d7b0 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
2d7c0 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
2d7d0 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
2d7e0 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
2d7f0 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
2d800 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
2d810 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
2d820 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
2d830 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
2d840 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2d850 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
2d860 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
2d870 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
2d880 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
2d890 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
2d8a0 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
2d8b0 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
2d8c0 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
2d8d0 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
2d8e0 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
2d8f0 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
2d900 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
2d910 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
2d920 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
2d930 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
2d940 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
2d950 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
2d960 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
2d970 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
2d980 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
2d990 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
2d9a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
2d9b0 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
2d9c0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
2d9d0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2d9e0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
2d9f0 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68   on disk..** ^Th
2da00 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2da10 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66  eadonly() interf
2da20 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2da30 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e   for [BEGIN] sin
2da40 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65  ce.** [BEGIN] me
2da50 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e  rely sets intern
2da60 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68  al flags, but th
2da70 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49  e [BEGIN|BEGIN I
2da80 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a  MMEDIATE] and.**
2da90 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58   [BEGIN|BEGIN EX
2daa0 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64  CLUSIVE] command
2dab0 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64  s do touch the d
2dac0 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a  atabase and so.*
2dad0 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2dae0 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e  eadonly() return
2daf0 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73  s false for thos
2db00 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 53  e commands..*/.S
2db10 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2db20 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2db30 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  nly(sqlite3_stmt
2db40 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2db50 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
2db60 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72  mine If A Prepar
2db70 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73  ed Statement Has
2db80 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d   Been Reset.** M
2db90 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2dba0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2dbb0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2dbc0 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (S) interface re
2dbd0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
2dbe0 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20  zero) if the.** 
2dbf0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2dc00 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20  ent] S has been 
2dc10 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74  stepped at least
2dc20 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20   once using .** 
2dc30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2dc40 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65  ] but has neithe
2dc50 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74  r run to complet
2dc60 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a  ion (returned.**
2dc70 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66   [SQLITE_DONE] f
2dc80 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rom [sqlite3_ste
2dc90 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65  p(S)]) nor.** be
2dca0 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b  en reset using [
2dcb0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
2dcc0 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2dcd0 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a  _stmt_busy(S).**
2dce0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2dcf0 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73  ns false if S is
2dd00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2dd10 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20    If S is not a 
2dd20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
2dd30 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f   and is not a po
2dd40 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64  inter to a valid
2dd50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2dd60 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c  ment].** object,
2dd70 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2dd80 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  or is undefined 
2dd90 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
2dda0 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  esirable..**.** 
2ddb0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
2ddc0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f  an be used in co
2ddd0 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74  mbination [sqlit
2dde0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a  e3_next_stmt()].
2ddf0 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c  ** to locate all
2de00 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2de10 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20  ents associated 
2de20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20  with a database 
2de30 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
2de40 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20  hat are in need 
2de50 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20  of being reset. 
2de60 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65   This can be use
2de70 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c  d,.** for exampl
2de80 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63  e, in diagnostic
2de90 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61   routines to sea
2dea0 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64  rch for prepared
2deb0 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20   .** statements 
2dec0 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67  that are holding
2ded0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f   a transaction o
2dee0 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  pen..*/.SQLITE_A
2def0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
2df00 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
2df10 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2df20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
2df30 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
2df40 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
2df50 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
2df60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
2df70 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
2df80 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
2df90 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2dfa0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2dfb0 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
2dfc0 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
2dfd0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
2dfe0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
2dff0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
2e000 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
2e010 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
2e020 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
2e030 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
2e040 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
2e050 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
2e060 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
2e070 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2e080 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
2e090 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
2e0a0 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
2e0b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
2e0c0 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
2e0d0 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
2e0e0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
2e0f0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2e100 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
2e110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2e120 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
2e130 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
2e140 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
2e150 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
2e160 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e170 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
2e180 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
2e190 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
2e1a0 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
2e1b0 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
2e1c0 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
2e1d0 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
2e1e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2e1f0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
2e200 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74  value_dup()] int
2e210 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2e220 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20  ed to construct 
2e230 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63  a new .** protec
2e240 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e250 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74  e from an unprot
2e260 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e270 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
2e280 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
2e290 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
2e2a0 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
2e2b0 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
2e2c0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
2e2d0 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
2e2e0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
2e2f0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2e300 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2e310 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
2e320 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
2e330 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2e340 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2e350 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
2e360 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
2e370 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
2e380 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
2e390 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
2e3a0 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
2e3b0 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
2e3c0 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
2e3d0 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
2e3e0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
2e3f0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
2e400 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
2e410 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2e420 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
2e430 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
2e440 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
2e450 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
2e460 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2e470 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2e480 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2e490 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
2e4a0 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
2e4b0 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
2e4c0 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
2e4d0 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
2e4e0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
2e4f0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
2e500 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
2e510 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
2e520 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
2e530 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2e540 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2e550 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2e560 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
2e570 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
2e580 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2e590 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2e5a0 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
2e5b0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
2e5c0 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
2e5d0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
2e5e0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
2e5f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2e600 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
2e610 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
2e620 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2e630 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2e640 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2e650 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2e660 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
2e670 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
2e680 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e690 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
2e6a0 75 73 65 64 20 61 73 20 61 72 67 75 6d 65 6e 74  used as argument
2e6b0 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
2e6c0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2e6d0 2c 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  , [sqlite3_bind_
2e6e0 76 61 6c 75 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  value()], and.**
2e6f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e700 64 75 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  dup()]..** The [
2e710 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2e720 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
2e730 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
2e740 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
2e750 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
2e760 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e770 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
2e780 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2e790 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 6c 69  lite3_value sqli
2e7a0 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
2e7b0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
2e7c0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2e7d0 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
2e7e0 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
2e7f0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
2e800 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
2e810 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
2e820 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2e830 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
2e840 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
2e850 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
2e860 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
2e870 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
2e880 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2e890 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2e8a0 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
2e8b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e8c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2e8d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
2e8e0 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
2e8f0 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
2e900 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
2e910 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
2e920 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
2e930 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2e940 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2e950 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
2e960 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
2e970 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2e980 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
2e990 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
2e9a0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
2e9b0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
2e9c0 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
2e9d0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2e9e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
2e9f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
2ea00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ea10 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
2ea20 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
2ea30 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
2ea40 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
2ea50 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
2ea60 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
2ea70 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
2ea80 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
2ea90 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
2eaa0 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
2eab0 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
2eac0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2ead0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  _stmt.**.** ^(In
2eae0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2eaf0 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
2eb00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2eb10 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
2eb20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
2eb30 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
2eb40 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
2eb50 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
2eb60 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
2eb70 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
2eb80 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2eb90 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
2eba0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
2ebb0 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
2ebc0 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
2ebd0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2ebe0 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
2ebf0 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
2ec00 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
2ec10 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
2ec20 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
2ec30 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
2ec40 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
2ec50 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
2ec60 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
2ec70 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
2ec80 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
2ec90 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
2eca0 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
2ecb0 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
2ecc0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2ecd0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
2ece0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
2ecf0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2ed00 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
2ed10 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2ed20 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
2ed30 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
2ed40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2ed50 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
2ed60 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
2ed70 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2ed80 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
2ed90 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
2eda0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2edb0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2edc0 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
2edd0 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
2ede0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
2edf0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2ee00 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
2ee10 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
2ee20 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
2ee30 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
2ee40 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
2ee50 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2ee60 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
2ee70 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
2ee80 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
2ee90 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
2eea0 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
2eeb0 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2eec0 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
2eed0 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
2eee0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2eef0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2ef00 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
2ef10 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
2ef20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
2ef30 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
2ef40 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
2ef50 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
2ef60 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
2ef70 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
2ef80 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
2ef90 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
2efa0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2efb0 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
2efc0 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
2efd0 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
2efe0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
2eff0 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
2f000 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
2f010 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2f020 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2f030 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2f040 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2f050 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
2f060 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2f070 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2f080 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
2f090 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
2f0a0 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
2f0b0 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
2f0c0 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
2f0d0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
2f0e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
2f0f0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
2f100 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
2f110 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
2f120 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2f130 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2f140 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
2f150 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
2f160 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2f170 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
2f180 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
2f190 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
2f1a0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2f1b0 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
2f1c0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2f1d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2f1e0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2f1f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2f200 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
2f210 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
2f220 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
2f230 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
2f240 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
2f250 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
2f260 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
2f270 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2f280 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2f290 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2f2a0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
2f2b0 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
2f2c0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2f2d0 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
2f2e0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2f2f0 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
2f300 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2f310 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
2f320 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2f330 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2f340 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a  d_text64() then.
2f350 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  ** that paramete
2f360 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
2f370 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
2f380 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
2f390 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
2f3a0 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
2f3b0 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
2f3c0 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
2f3d0 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
2f3e0 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
2f3f0 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
2f400 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
2f410 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
2f420 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
2f430 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
2f440 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
2f450 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
2f460 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
2f470 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
2f480 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
2f490 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
2f4a0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
2f4b0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2f4c0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
2f4d0 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42  ment to the BLOB
2f4e0 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64   and string bind
2f4f0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ing interfaces.*
2f500 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  * is a destructo
2f510 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
2f520 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2f530 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
2f540 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
2f550 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
2f560 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2f570 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
2f580 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2f590 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
2f5a0 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
2f5b0 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e   bind API fails.
2f5c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2f5d0 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
2f5e0 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
2f5f0 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
2f600 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
2f610 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
2f620 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
2f630 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
2f640 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
2f650 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
2f660 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
2f670 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2f680 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
2f690 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
2f6a0 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
2f6b0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
2f6c0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2f6d0 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
2f6e0 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
2f6f0 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
2f700 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2f710 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
2f720 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67  * ^The sixth arg
2f730 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2f740 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d  _bind_text64() m
2f750 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a  ust be one of.**
2f760 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2f770 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
2f780 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2f790 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2f7a0 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63  16LE].** to spec
2f7b0 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ify the encoding
2f7c0 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20   of the text in 
2f7d0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2f7e0 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ter.  If.** the 
2f7f0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2f800 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2f810 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f  ext64() is not o
2f820 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c  ne of the.** all
2f830 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77  owed values show
2f840 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74  n above, or if t
2f850 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
2f860 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a   is different.**
2f870 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69   from the encodi
2f880 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ng specified by 
2f890 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65  the sixth parame
2f8a0 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ter, then the be
2f8b0 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
2f8c0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2f8d0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2f8e0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
2f8f0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
2f900 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
2f910 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
2f920 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
2f930 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
2f940 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
2f950 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
2f960 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
2f970 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
2f980 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
2f990 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
2f9a0 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
2f9b0 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
2f9c0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2f9d0 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
2f9e0 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
2f9f0 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
2fa00 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
2fa10 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
2fa20 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
2fa30 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
2fa40 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
2fa50 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
2fa60 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
2fa70 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
2fa80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2fa90 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50  nd_pointer(S,I,P
2faa0 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 61  ,T,D) routine ca
2fab0 75 73 65 73 20 74 68 65 20 49 2d 74 68 20 70 61  uses the I-th pa
2fac0 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70  rameter in.** [p
2fad0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fae0 74 5d 20 53 20 74 6f 20 68 61 76 65 20 61 6e 20  t] S to have an 
2faf0 53 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c  SQL value of NUL
2fb00 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f 20 62  L, but to also b
2fb10 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  e.** associated 
2fb20 77 69 74 68 20 74 68 65 20 70 6f 69 6e 74 65 72  with the pointer
2fb30 20 50 20 6f 66 20 74 79 70 65 20 54 2e 20 20 5e   P of type T.  ^
2fb40 44 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  D is either a NU
2fb50 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a  LL pointer or.**
2fb60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2fb70 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
2fb80 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69  ion for P. ^SQLi
2fb90 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
2fba0 68 65 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72  he.** destructor
2fbb0 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65   D with a single
2fbc0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 50 20 77   argument of P w
2fbd0 68 65 6e 20 69 74 20 69 73 20 66 69 6e 69 73 68  hen it is finish
2fbe0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20  ed using.** P.  
2fbf0 54 68 65 20 54 20 70 61 72 61 6d 65 74 65 72 20  The T parameter 
2fc00 73 68 6f 75 6c 64 20 62 65 20 61 20 73 74 61 74  should be a stat
2fc10 69 63 20 73 74 72 69 6e 67 2c 20 70 72 65 66 65  ic string, prefe
2fc20 72 61 62 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a  rably a string.*
2fc30 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68 65 20 73  * literal. The s
2fc40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
2fc50 74 65 72 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ter() routine is
2fc60 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
2fc70 5b 70 6f 69 6e 74 65 72 20 70 61 73 73 69 6e 67  [pointer passing
2fc80 20 69 6e 74 65 72 66 61 63 65 5d 20 61 64 64 65   interface] adde
2fc90 64 20 66 6f 72 20 53 51 4c 69 74 65 20 33 2e 32  d for SQLite 3.2
2fca0 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  0.0..**.** ^If a
2fcb0 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
2fcc0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2fcd0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
2fce0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
2fcf0 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
2fd00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fd10 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
2fd20 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2fd30 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
2fd40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2fd50 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
2fd60 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
2fd70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2fd80 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
2fd90 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
2fda0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2fdb0 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
2fdc0 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
2fdd0 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
2fde0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2fdf0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
2fe00 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
2fe10 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
2fe20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2fe30 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
2fe40 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
2fe50 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
2fe60 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
2fe70 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
2fe80 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
2fe90 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
2fea0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
2feb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2fec0 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
2fed0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
2fee0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
2fef0 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
2ff00 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
2ff10 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
2ff20 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f  .** ^[SQLITE_TOO
2ff30 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65  BIG] might be re
2ff40 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69  turned if the si
2ff50 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f  ze of a string o
2ff60 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64  r BLOB.** exceed
2ff70 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64  s limits imposed
2ff80 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
2ff90 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
2ffa0 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a  T_LENGTH]) or.**
2ffb0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e   [SQLITE_MAX_LEN
2ffc0 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  GTH]..** ^[SQLIT
2ffd0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
2ffe0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
2fff0 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
30000 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
30010 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
30020 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
30030 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
30040 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
30050 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
30060 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
30070 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
30080 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
30090 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
300a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
300b0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
300c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
300d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
300e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
300f0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
30100 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
30110 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
30120 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
30130 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69  bind_blob64(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 76 6f 69 64 2a 2c 20 73 71 6c  const void*, 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 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
30190 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
301a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
301b0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
301c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
301d0 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ble);.SQLITE_API
301e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
301f0 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
30200 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
30210 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
30220 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
30230 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
30240 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
30250 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
30260 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
30270 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
30280 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  tmt*, int);.SQLI
30290 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
302a0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
302b0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63  ite3_stmt*,int,c
302c0 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76  onst char*,int,v
302d0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
302e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
302f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
30300 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
30310 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
30320 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
30330 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
30340 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
30350 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c  _bind_text64(sql
30360 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
30370 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
30380 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
30390 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
303a0 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
303b0 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20  oid*), unsigned 
303c0 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a  char encoding);.
303d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
303e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
303f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
30400 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
30410 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
30420 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
30430 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72  te3_bind_pointer
30440 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30450 69 6e 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e 73  int, void*, cons
30460 74 20 63 68 61 72 2a 2c 76 6f 69 64 28 2a 29 28  t char*,void(*)(
30470 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
30480 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
30490 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
304a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
304b0 2c 20 69 6e 74 20 6e 29 3b 0a 53 51 4c 49 54 45  , int n);.SQLITE
304c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
304d0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34  _bind_zeroblob64
304e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
304f0 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  int, sqlite3_uin
30500 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t64);../*.** CAP
30510 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
30520 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a   SQL Parameters.
30530 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
30540 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
30550 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
30560 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
30570 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
30580 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
30590 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
305a0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
305b0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
305c0 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
305d0 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
305e0 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
305f0 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
30600 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
30610 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
30620 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
30630 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
30640 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
30650 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
30660 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
30670 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
30680 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
30690 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
306a0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
306b0 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
306c0 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
306d0 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
306e0 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
306f0 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
30700 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
30710 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
30720 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
30730 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
30740 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
30750 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
30760 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
30770 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
30780 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
30790 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
307a0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
307b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
307c0 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
307d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
307e0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
307f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
30800 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
30810 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
30820 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
30830 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30840 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
30850 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54  Parameter.** MET
30860 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
30870 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
30880 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30890 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
308a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
308b0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
308c0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
308d0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
308e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
308f0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
30900 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
30910 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
30920 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
30930 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
30940 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
30950 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
30960 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
30970 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
30980 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
30990 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
309a0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
309b0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
309c0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
309d0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
309e0 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
309f0 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
30a00 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
30a10 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
30a20 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
30a30 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
30a40 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
30a50 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
30a60 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
30a70 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
30a80 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
30a90 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
30aa0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
30ab0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
30ac0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
30ad0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
30ae0 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
30af0 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
30b00 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
30b10 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
30b20 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
30b30 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
30b40 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
30b50 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
30b60 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
30b70 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
30b80 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
30b90 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
30ba0 65 70 61 72 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b  epare16()],.** [
30bb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
30bc0 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  6_v2()], or [sql
30bd0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
30be0 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  3()]..**.** See 
30bf0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
30c00 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
30c10 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
30c20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30c30 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
30c40 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
30c50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
30c60 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
30c70 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
30c80 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
30c90 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
30ca0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30cb0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30cc0 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
30cd0 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
30ce0 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45  Given Name.** ME
30cf0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
30d00 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
30d10 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
30d20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
30d30 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
30d40 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
30d50 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
30d60 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
30d70 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
30d80 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
30d90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
30da0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
30db0 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
30dc0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
30dd0 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
30de0 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
30df0 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
30e00 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
30e10 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
30e20 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
30e30 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
30e40 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
30e50 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
30e60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
30e70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 0a 2a  are16_v2()] or.*
30e80 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
30e90 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v3()]..**.*
30ea0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
30eb0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
30ec0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
30ed0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
30ee0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
30ef0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
30f00 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30f10 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a  ter_name()]..*/.
30f20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
30f30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30f40 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
30f50 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
30f60 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
30f70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30f80 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
30f90 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
30fa0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
30fb0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
30fc0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  mt.**.** ^Contra
30fd0 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
30fe0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
30ff0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
31000 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
31010 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
31020 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
31030 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
31040 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
31050 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
31060 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
31070 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
31080 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c   to NULL..*/.SQL
31090 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
310a0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
310b0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
310c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
310d0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
310e0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
310f0 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
31100 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
31110 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
31120 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
31130 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
31140 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
31150 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
31160 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66   statement]. ^If
31170 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
31180 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d 65  turns 0, that me
31190 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65  ans the .** [pre
311a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
311b0 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 61   returns no data
311c0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
311d0 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e   [UPDATE])..** ^
311e0 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62 65  However, just be
311f0 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  cause this routi
31200 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73  ne returns a pos
31210 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f 65  itive number doe
31220 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68  s not.** mean th
31230 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72  at one or more r
31240 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c 6c  ows of data will
31250 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   be returned.  ^
31260 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  A SELECT stateme
31270 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79  nt.** will alway
31280 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69 76  s have a positiv
31290 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
312a0 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65 70  _count() but dep
312b0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a  ending on the.**
312c0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
312d0 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
312e0 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c  e table content,
312f0 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72 6e   it might return
31300 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20   no rows..**.** 
31310 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
31320 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
31330 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
31340 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
31350 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
31360 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
31370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
31380 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
31390 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
313a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
313b0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
313c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
313d0 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
313e0 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
313f0 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
31400 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
31410 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
31420 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
31430 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
31440 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
31450 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
31460 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
31470 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
31480 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
31490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
314a0 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
314b0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
314c0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
314d0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
314e0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
314f0 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
31500 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
31510 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
31520 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
31530 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
31540 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
31550 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
31560 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
31570 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
31580 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
31590 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
315a0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
315b0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
315c0 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
315d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
315e0 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
315f0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
31600 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
31610 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
31620 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
31630 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
31640 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
31650 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
31660 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
31670 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
31680 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
31690 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
316a0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
316b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
316c0 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
316d0 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
316e0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
316f0 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
31700 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
31710 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
31720 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
31730 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
31740 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
31750 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
31760 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
31770 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
31780 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
31790 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
317a0 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
317b0 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
317c0 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
317d0 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
317e0 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
317f0 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
31800 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
31810 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
31820 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
31830 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
31840 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
31850 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
31860 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
31870 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  next..*/.SQLITE_
31880 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
31890 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
318a0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
318b0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54  *, int N);.SQLIT
318c0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
318d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
318e0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
318f0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
31900 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31910 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
31920 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
31930 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31940 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
31950 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
31960 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
31970 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
31980 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
31990 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
319a0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
319b0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
319c0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
319d0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
319e0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
319f0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
31a00 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
31a10 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
31a20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
31a30 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
31a40 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
31a50 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
31a60 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
31a70 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
31a80 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
31a90 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
31aa0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
31ab0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
31ac0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
31ad0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
31ae0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
31af0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
31b00 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
31b10 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
31b20 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
31b30 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
31b40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
31b50 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
31b60 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
31b70 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
31b80 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
31b90 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
31ba0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
31bb0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
31bc0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
31bd0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
31be0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
31bf0 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
31c00 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
31c10 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
31c20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
31c30 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
31c40 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
31c50 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
31c60 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
31c70 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
31c80 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
31c90 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
31ca0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
31cb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31cc0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
31cd0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
31ce0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
31cf0 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
31d00 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
31d10 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
31d20 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
31d30 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
31d40 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
31d50 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
31d60 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
31d70 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
31d80 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
31d90 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
31da0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
31db0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
31dc0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
31dd0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
31de0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
31df0 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
31e00 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
31e10 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
31e20 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
31e30 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
31e40 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
31e50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
31e60 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
31e70 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
31e80 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
31e90 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
31ea0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
31eb0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
31ec0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
31ed0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
31ee0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
31ef0 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
31f00 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
31f10 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
31f20 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
31f30 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
31f40 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
31f50 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
31f60 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
31f70 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
31f80 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
31f90 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
31fa0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
31fb0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
31fc0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
31fd0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
31fe0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
31ff0 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
32000 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
32010 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
32020 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
32030 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
32040 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
32050 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
32060 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
32070 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
32080 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
32090 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
320a0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
320b0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
320c0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
320d0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
320e0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
320f0 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
32100 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
32110 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
32120 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
32130 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
32140 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
32150 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
32160 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
32170 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
32180 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
32190 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
321a0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
321b0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
321c0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
321d0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
321e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
321f0 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
32200 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
32210 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
32220 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
32230 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
32240 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
32250 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
32260 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
32270 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
32280 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
32290 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
322a0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
322b0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
322c0 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
322d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
322e0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
322f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
32300 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
32310 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
32320 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
32330 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
32340 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
32350 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
32360 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
32370 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
32380 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
32390 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
323a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
323b0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
323c0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
323d0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
323e0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
323f0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
32400 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
32410 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
32420 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
32430 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
32440 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
32450 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
32460 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
32470 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
32480 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
32490 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
324a0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
324b0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
324c0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
324d0 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
324e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
324f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
32500 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
32510 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
32520 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
32530 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
32540 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
32550 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
32560 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
32570 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
32580 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
32590 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
325a0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
325b0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
325c0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
325d0 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
325e0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
325f0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
32600 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
32610 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
32620 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
32630 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
32640 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
32650 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
32660 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
32670 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
32680 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
32690 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
326a0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
326b0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
326c0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
326d0 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
326e0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
326f0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
32700 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
32710 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
32720 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
32730 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
32740 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
32750 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
32760 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
32770 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
32780 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
32790 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
327a0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
327b0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
327c0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
327d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
327e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
327f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
32800 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
32810 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
32820 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
32830 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
32840 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
32850 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
32860 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
32870 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
32880 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
32890 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
328a0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
328b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
328c0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
328d0 61 72 65 64 20 75 73 69 6e 67 20 61 6e 79 20 6f  ared using any o
328e0 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  f.** [sqlite3_pr
328f0 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
32900 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
32910 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
32920 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a  epare16_v2()],.*
32930 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  * or [sqlite3_pr
32940 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 6f 72  epare16_v3()] or
32950 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
32960 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
32970 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32980 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
32990 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
329a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
329b0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
329c0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
329d0 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
329e0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
329f0 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
32a00 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
32a10 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
32a20 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
32a30 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
32a40 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
32a50 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
32a60 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
32a70 58 22 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  X" interfaces.**
32a80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32a90 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v3()], [sqlite
32aa0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
32ab0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32ac0 65 31 36 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73  e16_v3()],.** [s
32ad0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
32ae0 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
32af0 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
32b00 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
32b10 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
32b20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32b30 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
32b40 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
32b50 76 58 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  vX" interface is
32b60 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
32b70 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
32b80 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
32b90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
32ba0 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
32bb0 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
32bc0 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
32bd0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
32be0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
32bf0 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
32c00 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
32c10 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
32c20 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
32c30 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
32c40 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
32c50 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
32c60 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
32c70 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
32c80 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
32c90 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
32ca0 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
32cb0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
32cc0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
32cd0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
32ce0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
32cf0 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
32d00 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
32d10 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
32d20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
32d30 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
32d40 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
32d50 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
32d60 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
32d70 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
32d80 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
32d90 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
32da0 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
32db0 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
32dc0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
32dd0 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
32de0 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a  urs within an.**
32df0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
32e00 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
32e10 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
32e20 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
32e30 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
32e40 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ing..**.** ^[SQL
32e50 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
32e60 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
32e70 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
32e80 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
32e90 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
32ea0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
32eb0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
32ec0 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
32ed0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
32ee0 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
32ef0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
32f00 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
32f10 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
32f20 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
32f30 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
32f40 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te..**.** ^If th
32f50 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
32f60 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
32f70 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
32f80 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
32f90 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
32fa0 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
32fb0 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
32fc0 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
32fd0 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
32fe0 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
32ff0 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
33000 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
33010 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
33020 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
33030 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
33040 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
33050 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
33060 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
33070 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  * ^[SQLITE_ERROR
33080 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
33090 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
330a0 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
330b0 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
330c0 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
330d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
330e0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
330f0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
33100 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
33110 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
33120 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
33130 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
33140 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  g()]..** ^With t
33150 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
33160 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
33170 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
33180 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
33190 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
331a0 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
331b0 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
331c0 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
331d0 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
331e0 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
331f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
33200 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
33210 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33220 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22  ent].  ^In the "
33230 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
33240 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
33250 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
33260 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
33270 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
33280 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
33290 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
332a0 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
332b0 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
332c0 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
332d0 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
332e0 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
332f0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
33300 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
33310 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
33320 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
33330 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
33340 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
33350 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
33360 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
33370 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
33380 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
33390 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
333a0 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
333b0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
333c0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
333d0 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
333e0 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
333f0 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
33400 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
33410 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69  ** For all versi
33420 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70  ons of SQLite up
33430 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e   to and includin
33440 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61  g 3.6.23.1, a ca
33450 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
33460 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72  3_reset()] was r
33470 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71  equired after sq
33480 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74  lite3_step() ret
33490 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a  urned anything.*
334a0 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  * other than [SQ
334b0 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65  LITE_ROW] before
334c0 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
334d0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
334e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
334f0 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73    Failure to res
33500 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
33510 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
33520 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
33530 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75  et()] would resu
33540 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  lt in an [SQLITE
33550 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20  _MISUSE] return 
33560 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
33570 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
33580 65 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e  er [version 3.6.
33590 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33  23.1] ([dateof:3
335a0 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c  .6.23.1],.** sql
335b0 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
335c0 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
335d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
335e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
335f0 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
33600 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
33610 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
33620 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
33630 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
33640 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
33650 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
33660 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
33670 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
33680 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
33690 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
336a0 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
336b0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
336c0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
336d0 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
336e0 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
336f0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
33700 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
33710 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
33720 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
33730 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
33740 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
33750 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
33760 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
33770 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
33780 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
33790 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
337a0 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
337b0 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
337c0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
337d0 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
337e0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
337f0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
33800 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
33810 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
33820 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
33830 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
33840 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
33850 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
33860 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
33870 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
33880 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
33890 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
338a0 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
338b0 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
338c0 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
338d0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
338e0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
338f0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
33900 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
33910 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
33920 70 61 72 65 5f 76 33 28 29 5d 20 6f 72 20 5b 73  pare_v3()] or [s
33930 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
33940 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  2()].** or [sqli
33950 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
33960 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
33970 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20  prepare16_v3()] 
33980 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
33990 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
339a0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
339b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
339c0 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
339d0 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
339e0 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
339f0 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
33a00 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
33a10 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
33a20 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
33a30 6f 66 20 74 68 65 20 22 76 58 22 20 69 6e 74 65  of the "vX" inte
33a40 72 66 61 63 65 73 20 69 73 20 72 65 63 6f 6d 6d  rfaces is recomm
33a50 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ended..*/.SQLITE
33a60 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
33a70 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
33a80 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
33a90 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
33aa0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
33ab0 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48  sult set.** METH
33ac0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
33ad0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33ae0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
33af0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
33b00 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
33b10 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
33b20 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
33b30 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
33b40 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
33b50 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
33b60 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
33b70 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
33b80 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
33b90 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
33ba0 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
33bb0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
33bc0 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
33bd0 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
33be0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
33bf0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
33c00 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
33c10 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
33c20 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
33c30 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
33c40 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
33c50 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
33c60 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
33c70 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
33c80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
33c90 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
33ca0 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
33cb0 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
33cc0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
33cd0 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
33ce0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
33cf0 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
33d00 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
33d10 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
33d20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
33d30 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
33d40 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
33d50 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
33d60 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
33d70 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
33d80 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
33d90 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
33da0 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
33db0 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
33dc0 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
33dd0 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
33de0 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
33df0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
33e00 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
33e10 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )].*/.SQLITE_API
33e20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74   int sqlite3_dat
33e30 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
33e40 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
33e50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
33e60 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
33e70 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
33e80 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
33e90 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
33ea0 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
33eb0 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
33ec0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
33ed0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
33ee0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
33ef0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
33f00 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
33f10 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
33f20 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
33f30 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
33f40 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
33f50 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
33f60 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
33f70 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
33f80 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
33f90 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
33fa0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
33fb0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
33fc0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
33fd0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
33fe0 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
33ff0 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
34000 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
34010 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
34020 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
34030 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
34040 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
34050 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
34060 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
34070 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
34080 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
34090 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
340a0 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
340b0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
340c0 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
340d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
340e0 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
340f0 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
34100 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
34110 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
34120 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
34130 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
34140 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
34150 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
34160 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
34170 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
34180 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
34190 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
341a0 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
341b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
341c0 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f  ** <b>Summary:</
341d0 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  b>.** <blockquot
341e0 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  e><table border=
341f0 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30 20  0 cellpadding=0 
34200 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a 2a  cellspacing=0>.*
34210 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
34220 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
34230 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
34240 64 3e 42 4c 4f 42 20 72 65 73 75 6c 74 0a 2a 2a  d>BLOB result.**
34250 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
34260 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
34270 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  e</b><td>&rarr;<
34280 74 64 3e 52 45 41 4c 20 72 65 73 75 6c 74 0a 2a  td>REAL result.*
34290 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
342a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c  ite3_column_int<
342b0 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
342c0 3e 33 32 2d 62 69 74 20 49 4e 54 45 47 45 52 20  >32-bit INTEGER 
342d0 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
342e0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
342f0 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62 3e 3c 74 64  umn_int64</b><td
34300 3e 26 72 61 72 72 3b 3c 74 64 3e 36 34 2d 62 69  >&rarr;<td>64-bi
34310 74 20 49 4e 54 45 47 45 52 20 72 65 73 75 6c 74  t INTEGER result
34320 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
34330 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
34340 78 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b  xt</b><td>&rarr;
34350 3c 74 64 3e 55 54 46 2d 38 20 54 45 58 54 20 72  <td>UTF-8 TEXT r
34360 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  esult.** <tr><td
34370 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ><b>sqlite3_colu
34380 6d 6e 5f 74 65 78 74 31 36 3c 2f 62 3e 3c 74 64  mn_text16</b><td
34390 3e 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 31  >&rarr;<td>UTF-1
343a0 36 20 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a  6 TEXT result.**
343b0 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69   <tr><td><b>sqli
343c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
343d0 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
343e0 64 3e 54 68 65 20 72 65 73 75 6c 74 20 61 73 20  d>The result as 
343f0 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  an .** [sqlite3_
34400 76 61 6c 75 65 7c 75 6e 70 72 6f 74 65 63 74 65  value|unprotecte
34410 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34420 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e   object..** <tr>
34430 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e  <td>&nbsp;<td>&n
34440 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a  bsp;<td>&nbsp;.*
34450 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c  * <tr><td><b>sql
34460 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34470 73 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c  s</b><td>&rarr;<
34480 74 64 3e 53 69 7a 65 20 6f 66 20 61 20 42 4c 4f  td>Size of a BLO
34490 42 0a 2a 2a 20 6f 72 20 61 20 55 54 46 2d 38 20  B.** or a UTF-8 
344a0 54 45 58 54 20 72 65 73 75 6c 74 20 69 6e 20 62  TEXT result in b
344b0 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ytes.** <tr><td>
344c0 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
344d0 6e 5f 62 79 74 65 73 31 36 26 6e 62 73 70 3b 26  n_bytes16&nbsp;&
344e0 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64  nbsp;</b>.** <td
344f0 3e 26 72 61 72 72 3b 26 6e 62 73 70 3b 26 6e 62  >&rarr;&nbsp;&nb
34500 73 70 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 55  sp;<td>Size of U
34510 54 46 2d 31 36 0a 2a 2a 20 54 45 58 54 20 69 6e  TF-16.** TEXT in
34520 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74   bytes.** <tr><t
34530 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
34540 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e 3c 74 64 3e  umn_type</b><td>
34550 26 72 61 72 72 3b 3c 74 64 3e 44 65 66 61 75 6c  &rarr;<td>Defaul
34560 74 0a 2a 2a 20 64 61 74 61 74 79 70 65 20 6f 66  t.** datatype of
34570 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 3c   the result.** <
34580 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75  /table></blockqu
34590 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65  ote>.**.** <b>De
345a0 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a  tails:</b>.**.**
345b0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
345c0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
345d0 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
345e0 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
345f0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
34600 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
34610 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
34620 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
34630 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
34640 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
34650 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
34660 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
34670 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
34680 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
34690 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
346a0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
346b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
346c0 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
346d0 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
346e0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
346f0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
34700 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
34710 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
34720 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
34730 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
34740 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
34750 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
34760 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
34770 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
34780 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
34790 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
347a0 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
347b0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
347c0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
347d0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
347e0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
347f0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
34800 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
34810 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
34820 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
34830 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
34840 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
34850 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
34860 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
34870 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
34880 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
34890 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
348a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
348b0 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
348c0 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
348d0 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
348e0 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
348f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
34900 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
34910 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
34920 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
34930 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
34940 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
34950 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
34960 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
34970 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
34980 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
34990 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
349a0 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
349b0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
349c0 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
349d0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
349e0 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
349f0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
34a00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
34a10 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
34a20 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
34a30 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
34a40 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
34a50 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
34a60 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
34a70 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
34a80 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
34a90 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
34aa0 68 65 20 66 69 72 73 74 20 73 69 78 20 69 6e 74  he first six int
34ab0 65 72 66 61 63 65 73 20 28 5f 62 6c 6f 62 2c 20  erfaces (_blob, 
34ac0 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f  _double, _int, _
34ad0 69 6e 74 36 34 2c 20 5f 74 65 78 74 2c 20 61 6e  int64, _text, an
34ae0 64 20 5f 74 65 78 74 31 36 29 0a 2a 2a 20 65 61  d _text16).** ea
34af0 63 68 20 72 65 74 75 72 6e 20 74 68 65 20 76 61  ch return the va
34b00 6c 75 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20  lue of a result 
34b10 63 6f 6c 75 6d 6e 20 69 6e 20 61 20 73 70 65 63  column in a spec
34b20 69 66 69 63 20 64 61 74 61 20 66 6f 72 6d 61 74  ific data format
34b30 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 72 65 73  .  If.** the res
34b40 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f  ult column is no
34b50 74 20 69 6e 69 74 69 61 6c 6c 79 20 69 6e 20 74  t initially in t
34b60 68 65 20 72 65 71 75 65 73 74 65 64 20 66 6f 72  he requested for
34b70 6d 61 74 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  mat (for example
34b80 2c 0a 2a 2a 20 69 66 20 74 68 65 20 71 75 65 72  ,.** if the quer
34b90 79 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  y returns an int
34ba0 65 67 65 72 20 62 75 74 20 74 68 65 20 73 71 6c  eger but the sql
34bb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
34bc0 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
34bd0 69 73 20 75 73 65 64 20 74 6f 20 65 78 74 72 61  is used to extra
34be0 63 74 20 74 68 65 20 76 61 6c 75 65 29 20 74 68  ct the value) th
34bf0 65 6e 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  en an automatic 
34c00 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
34c10 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a  is performed..**
34c20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34c30 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
34c40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
34c50 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
34c60 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
34c70 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
34c80 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
34c90 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
34ca0 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
34cb0 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
34cc0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
34cd0 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
34ce0 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
34cf0 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
34d00 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
34d10 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a  SQLITE_NULL]..**
34d20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
34d30 65 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  e of sqlite3_col
34d40 75 6d 6e 5f 74 79 70 65 28 29 20 63 61 6e 20 62  umn_type() can b
34d50 65 20 75 73 65 64 20 74 6f 20 64 65 63 69 64 65  e used to decide
34d60 20 77 68 69 63 68 0a 2a 2a 20 6f 66 20 74 68 65   which.** of the
34d70 20 66 69 72 73 74 20 73 69 78 20 69 6e 74 65 72   first six inter
34d80 66 61 63 65 20 73 68 6f 75 6c 64 20 62 65 20 75  face should be u
34d90 73 65 64 20 74 6f 20 65 78 74 72 61 63 74 20 74  sed to extract t
34da0 68 65 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e  he column value.
34db0 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 72 65  .** The value re
34dc0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
34dd0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
34de0 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
34df0 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f  ul if no.** auto
34e00 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65  matic type conve
34e10 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
34e20 72 72 65 64 20 66 6f 72 20 74 68 65 20 76 61 6c  rred for the val
34e30 75 65 20 69 6e 20 71 75 65 73 74 69 6f 6e 2e 20  ue in question. 
34e40 20 0a 2a 2a 20 41 66 74 65 72 20 61 20 74 79 70   .** After a typ
34e50 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 20 74 68  e conversion, th
34e60 65 20 72 65 73 75 6c 74 20 6f 66 20 63 61 6c 6c  e result of call
34e70 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ing sqlite3_colu
34e80 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 69 73 20  mn_type().** is 
34e90 75 6e 64 65 66 69 6e 65 64 2c 20 74 68 6f 75 67  undefined, thoug
34ea0 68 20 68 61 72 6d 6c 65 73 73 2e 20 20 46 75 74  h harmless.  Fut
34eb0 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
34ec0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
34ed0 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
34ee0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
34ef0 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
34f00 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
34f10 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
34f20 20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   If the result i
34f30 73 20 61 20 42 4c 4f 42 20 6f 72 20 61 20 54 45  s a BLOB or a TE
34f40 58 54 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  XT string, then 
34f50 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
34f60 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 6f 72  mn_bytes().** or
34f70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34f80 62 79 74 65 73 31 36 28 29 20 69 6e 74 65 72 66  bytes16() interf
34f90 61 63 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  aces can be used
34fa0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
34fb0 65 20 73 69 7a 65 0a 2a 2a 20 6f 66 20 74 68 61  e size.** of tha
34fc0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
34fd0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
34fe0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
34ff0 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
35000 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
35010 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
35020 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
35030 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
35040 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
35050 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
35060 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
35070 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
35080 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
35090 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
350a0 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
350b0 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
350c0 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
350d0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
350e0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
350f0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
35100 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
35110 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
35120 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
35130 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
35140 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
35150 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
35160 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
35170 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
35180 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
35190 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
351a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
351b0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
351c0 20 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 20 72 65 74 75 72 6e 73 20  bytes() returns 
351e0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
351f0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
35200 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
35210 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
35220 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35230 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
35240 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
35250 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
35260 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
35270 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
35280 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
35290 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
352a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
352b0 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
352c0 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
352d0 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
352e0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
352f0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
35300 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
35310 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
35320 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
35330 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
35340 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
35350 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
35360 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
35370 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
35380 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
35390 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
353a0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
353b0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
353c0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
353d0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
353e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
353f0 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
35400 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
35410 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
35420 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
35430 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
35440 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
35450 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
35460 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
35470 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
35480 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
35490 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
354a0 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
354b0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
354c0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
354d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
354e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
354f0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
35500 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
35510 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
35520 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
35530 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
35540 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
35550 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
35560 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
35570 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
35580 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35590 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
355a0 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
355b0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
355c0 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
355d0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
355e0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
355f0 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
35600 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
35610 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
35620 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72  er..**.** <b>War
35630 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f  ning:</b> ^The o
35640 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
35650 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
35660 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
35670 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
35680 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
35690 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75  object.  In a mu
356a0 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69  ltithreaded envi
356b0 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75  ronment,.** an u
356c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
356d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
356e0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
356f0 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20   safely with.** 
35700 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
35710 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
35720 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
35730 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
35740 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
35750 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
35760 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
35770 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
35780 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
35790 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
357a0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
357b0 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
357c0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
357d0 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
357e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
357f0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
35800 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
35810 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69  s()], the behavi
35820 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  or is not thread
35830 73 61 66 65 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20  safe..** Hence, 
35840 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
35850 6d 6e 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  mn_value() inter
35860 66 61 63 65 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61  face.** is norma
35870 6c 6c 79 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20  lly only useful 
35880 77 69 74 68 69 6e 20 74 68 65 20 69 6d 70 6c 65  within the imple
35890 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a  mentation of .**
358a0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
358b0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
358c0 6f 6e 73 5d 20 6f 72 20 5b 76 69 72 74 75 61 6c  ons] or [virtual
358d0 20 74 61 62 6c 65 73 5d 2c 20 6e 6f 74 20 77 69   tables], not wi
358e0 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  thin.** top-leve
358f0 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  l application co
35900 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68  de..**.** The th
35910 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
35920 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76   attempt to conv
35930 65 72 74 20 74 68 65 20 64 61 74 61 74 79 70 65  ert the datatype
35940 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 0a   of the result..
35950 2a 2a 20 5e 46 6f 72 20 65 78 61 6d 70 6c 65 2c  ** ^For example,
35960 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
35970 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
35980 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
35990 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
359a0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
359b0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
359c0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
359d0 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
359e0 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
359f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
35a00 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
35a10 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
35a20 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
35a30 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
35a40 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
35a50 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
35a60 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
35a70 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
35a80 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
35a90 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
35aa0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
35ab0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
35ac0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
35ad0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
35ae0 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
35af0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
35b00 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
35b10 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
35b20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
35b30 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
35b40 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
35b50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
35b60 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
35b70 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
35b80 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
35b90 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
35ba0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
35bb0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
35bc0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
35bd0 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
35be0 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
35bf0 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
35c00 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
35c10 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
35c20 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
35c30 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
35c40 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
35c50 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
35c60 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
35c70 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
35c80 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
35c90 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
35ca0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
35cb0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
35cc0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
35cd0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
35ce0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
35cf0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
35d00 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
35d10 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41  BLOB    <td> [CA
35d20 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c  ST] to BLOB.** <
35d30 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
35d40 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
35d50 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
35d60 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
35d70 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
35d80 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
35d90 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
35da0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
35db0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
35dc0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
35dd0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
35de0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
35df0 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
35e00 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
35e10 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
35e20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
35e30 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
35e40 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
35e50 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
35e60 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
35e70 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
35e80 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
35e90 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
35ea0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
35eb0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
35ec0 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
35ed0 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
35ee0 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
35ef0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
35f00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35f10 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
35f20 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
35f30 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
35f40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
35f50 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
35f60 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
35f70 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
35f80 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
35f90 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
35fa0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
35fb0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
35fc0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
35fd0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
35fe0 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
35ff0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36000 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
36010 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36020 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
36030 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
36040 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
36050 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
36060 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
36070 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
36080 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
36090 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
360a0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
360b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
360c0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
360d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
360e0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
360f0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
36100 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
36110 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
36120 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
36130 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
36140 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
36150 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
36160 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
36170 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
36180 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
36190 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
361a0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
361b0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
361c0 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
361d0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
361e0 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
361f0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
36200 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
36210 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
36220 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
36230 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
36240 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
36250 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
36260 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
36270 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
36280 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
36290 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
362a0 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
362b0 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
362c0 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
362d0 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
362e0 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
362f0 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
36300 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
36310 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
36320 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
36330 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
36340 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
36350 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
36360 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  st policy is to 
36370 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
36380 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
36390 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
363a0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
363b0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
363c0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
363d0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
363e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
363f0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
36400 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36410 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
36420 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
36430 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
36440 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
36450 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
36460 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
36470 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
36480 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
36490 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
364a0 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
364b0 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
364c0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
364d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
364e0 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
364f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
36500 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
36510 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
36520 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
36530 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
36540 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
36550 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
36560 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
36570 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
36580 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
36590 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
365a0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
365b0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
365c0 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
365d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
365e0 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
365f0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
36600 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
36610 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
36620 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
36630 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
36640 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
36650 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36660 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  es()..**.** ^The
36670 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
36680 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
36690 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
366a0 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
366b0 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
366c0 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
366d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
366e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
366f0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
36700 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
36710 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65  called.  ^The me
36720 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
36730 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
36740 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
36750 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
36760 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74 20 70 61 73  lly.  Do not pas
36770 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
36780 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
36790 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
367a0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
367b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
367c0 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
367d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
367e0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
367f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
36800 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
36810 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
36820 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
36830 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
36840 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
36850 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
36860 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
36870 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
36880 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
36890 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
368a0 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
368b0 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
368c0 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
368d0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
368e0 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
368f0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
36900 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51  _NOMEM].)^.*/.SQ
36910 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
36920 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
36930 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
36940 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36950 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f  );.SQLITE_API do
36960 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
36970 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
36980 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
36990 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
369a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
369b0 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
369c0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
369d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
369e0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
369f0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
36a00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
36a10 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
36a20 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
36a30 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
36a40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
36a50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36a60 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
36a70 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
36a80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
36a90 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
36aa0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
36ab0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
36ac0 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
36ad0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
36ae0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36af0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
36b00 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
36b10 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
36b20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
36b30 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
36b40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
36b50 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
36b60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
36b70 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
36b80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
36b90 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
36ba0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
36bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36bc0 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
36bd0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
36be0 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55  Object.** DESTRU
36bf0 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74  CTOR: sqlite3_st
36c00 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
36c10 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
36c20 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
36c30 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
36c40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36c50 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
36c60 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
36c70 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
36c80 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
36c90 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
36ca0 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
36cb0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
36cc0 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
36cd0 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
36ce0 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
36cf0 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
36d00 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
36d10 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
36d20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
36d30 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
36d40 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
36d50 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
36d60 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
36d70 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
36d80 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
36d90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36da0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
36db0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
36dc0 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
36dd0 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
36de0 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
36df0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36e00 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
36e10 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
36e20 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
36e30 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
36e40 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
36e50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
36e60 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
36e70 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
36e80 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
36e90 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
36ea0 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
36eb0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
36ec0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
36ed0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
36ee0 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
36ef0 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
36f00 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
36f10 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
36f20 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
36f30 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
36f40 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
36f50 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
36f60 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
36f70 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
36f80 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
36f90 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
36fa0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
36fb0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
36fc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36fd0 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
36fe0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
36ff0 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
37000 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
37010 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
37020 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
37030 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
37040 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
37050 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
37060 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
37070 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
37080 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  rruption..*/.SQL
37090 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
370a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
370b0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
370c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
370d0 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
370e0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
370f0 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  bject.** METHOD:
37100 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
37110 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
37120 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
37130 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
37140 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
37150 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
37160 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
37170 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
37180 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
37190 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
371a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
371b0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
371c0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
371d0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
371e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
371f0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
37200 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
37210 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
37220 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
37230 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
37240 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
37250 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
37260 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
37270 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
37280 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
37290 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
372a0 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
372b0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
372c0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
372d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
372e0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
372f0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
37300 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
37310 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37320 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
37330 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
37340 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
37350 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
37360 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
37370 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
37380 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
37390 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
373a0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
373b0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
373c0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
373d0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
373e0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
373f0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
37400 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
37410 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
37420 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
37430 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
37440 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
37450 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
37460 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
37470 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
37480 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
37490 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
374a0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
374b0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
374c0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
374d0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
374e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
374f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
37500 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
37510 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
37520 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
37530 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
37540 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
37550 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
37560 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
37570 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
37580 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
37590 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
375a0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
375b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
375c0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
375d0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
375e0 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
375f0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
37600 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
37610 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
37620 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
37630 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
37640 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
37650 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
37660 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
37670 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
37680 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
37690 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
376a0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
376b0 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
376c0 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
376d0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
376e0 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
376f0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
37700 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
37710 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
37720 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
37730 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
37740 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
37750 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
37760 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
37770 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
37780 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
37790 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
377a0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
377b0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
377c0 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
377d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
377e0 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
377f0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
37800 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
37810 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
37820 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
37830 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
37840 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
37850 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37860 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
37870 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
37880 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
37890 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
378a0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
378b0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
378c0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
378d0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
378e0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
378f0 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
37900 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
37910 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
37920 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
37930 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
37940 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
37950 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
37960 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
37970 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
37980 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
37990 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
379a0 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
379b0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
379c0 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
379d0 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
379e0 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
379f0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
37a00 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
37a10 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
37a20 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
37a30 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
37a40 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
37a50 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
37a60 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
37a70 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
37a80 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
37a90 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
37aa0 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
37ab0 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
37ac0 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
37ad0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
37ae0 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
37af0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
37b00 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
37b10 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
37b20 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
37b30 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
37b40 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
37b50 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
37b60 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
37b70 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
37b80 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
37b90 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
37ba0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
37bb0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
37bc0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
37bd0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
37be0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
37bf0 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
37c00 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
37c10 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
37c20 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
37c30 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
37c40 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
37c50 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
37c60 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
37c70 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
37c80 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
37c90 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
37ca0 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
37cb0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
37cc0 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
37cd0 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
37ce0 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
37cf0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
37d00 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
37d10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37d20 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
37d30 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
37d40 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
37d50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
37d60 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
37d70 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
37d80 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
37d90 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
37da0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
37db0 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
37dc0 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
37dd0 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
37de0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
37df0 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
37e00 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
37e10 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
37e20 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
37e30 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
37e40 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
37e50 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
37e60 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
37e70 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
37e80 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
37e90 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
37ea0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
37eb0 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
37ec0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
37ed0 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
37ee0 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
37ef0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
37f00 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
37f10 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
37f20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
37f30 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
37f40 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
37f50 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
37f60 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
37f70 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
37f80 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
37f90 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
37fa0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
37fb0 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
37fc0 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
37fd0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
37fe0 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
37ff0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
38000 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
38010 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
38020 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
38030 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
38040 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
38050 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
38060 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
38070 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
38080 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
38090 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
380a0 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
380b0 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
380c0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
380d0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
380e0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
380f0 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
38100 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
38110 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
38120 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
38130 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
38140 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
38150 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
38160 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
38170 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
38180 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
38190 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
381a0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
381b0 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
381c0 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
381d0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
381e0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
381f0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
38200 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
38210 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
38220 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
38230 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
38240 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
38250 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
38260 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
38270 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
38280 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
38290 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
382a0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
382b0 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
382c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
382d0 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
382e0 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
382f0 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
38300 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
38310 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
38320 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
38330 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
38340 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
38350 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
38360 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
38370 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
38380 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
38390 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
383a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
383b0 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
383c0 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
383d0 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
383e0 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
383f0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
38400 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
38410 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
38420 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
38430 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
38440 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
38450 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
38460 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
38470 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
38480 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
38490 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
384a0 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
384b0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
384c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
384d0 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
384e0 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
384f0 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
38500 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
38510 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
38520 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
38530 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
38540 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
38550 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
38560 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
38570 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
38580 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
38590 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
385a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
385b0 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
385c0 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
385d0 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
385e0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
385f0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
38600 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
38610 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
38620 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
38630 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
38640 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
38650 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
38660 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
38670 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
38680 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
38690 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
386a0 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
386b0 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
386c0 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in whic