/ Hex Artifact Content
Login

Artifact e0be726ea6e4e6571724d39d242472ecd8bd1ba6f84ade88e1641bde98a6d02b:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35  /*.** 2001-09-15
0010: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0020: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0030: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0040: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0050: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0060: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0070: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0080: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0090: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
00a0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
00b0: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
00c0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
00d0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
00e0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
00f0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
0100: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
0110: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
0120: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0170: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
0180: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
0190: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
01a0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
01b0: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
01c0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
01d0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
01e0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
01f0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
0200: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
0210: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
0220: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
0230: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
0240: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
0250: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
0260: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
0270: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
0280: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
0290: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
02a0: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
02b0: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
02c0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
02d0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
02e0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
02f0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
0300: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
0310: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
0320: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
0330: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
0340: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
0350: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
0360: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
0370: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
0380: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
0390: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
03a0: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
03b0: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
03c0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
03d0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
03e0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
03f0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
0400: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
0410: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
0420: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
0430: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
0440: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
0450: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
0460: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
0470: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
0480: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
0490: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
04a0: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
04b0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
04c0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f  re supposed to o
04d0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  perate..**.** Th
04e0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66  e name of this f
04f0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67  ile under config
0500: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0510: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e  nt is "sqlite.h.
0520: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65  in"..** The make
0530: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20  file makes some 
0540: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f  minor changes to
0550: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68   this file (such
0560: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a   as inserting.**
0570: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d   the version num
0580: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73  ber) and changes
0590: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71   its name to "sq
05a0: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70  lite3.h" as.** p
05b0: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64  art of the build
05c0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66   process..*/.#if
05d0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23  ndef SQLITE3_H.#
05e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48  define SQLITE3_H
05f0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
0600: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
0610: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
0620: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
0630: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
0640: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
0650: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
0660: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66 20   C++..*/.#ifdef 
0670: 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74 65  __cplusplus.exte
0680: 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a  rn "C" {.#endif.
0690: 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20  ../*.** Provide 
06a0: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
06b0: 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20  verride linkage 
06c0: 66 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20  features of the 
06d0: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69  interface..*/.#i
06e0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54  fndef SQLITE_EXT
06f0: 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ERN.# define SQL
0700: 49 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72  ITE_EXTERN exter
0710: 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  n.#endif.#ifndef
0720: 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65   SQLITE_API.# de
0730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a  fine SQLITE_API.
0740: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
0750: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65  QLITE_CDECL.# de
0760: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43  fine SQLITE_CDEC
0770: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
0780: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a   SQLITE_APICALL.
0790: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
07a0: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
07b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 54  ifndef SQLITE_ST
07c0: 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  DCALL.# define S
07d0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 53 51  QLITE_STDCALL SQ
07e0: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
07f0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0800: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 20 64 65  TE_CALLBACK.# de
0810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4c 4c  fine SQLITE_CALL
0820: 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 69 66 6e  BACK.#endif.#ifn
0830: 64 65 66 20 53 51 4c 49 54 45 5f 53 59 53 41 50  def SQLITE_SYSAP
0840: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
0850: 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 69 66 0a  E_SYSAPI.#endif.
0860: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
0870: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
0880: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
0890: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
08a0: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
08b0: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
08c0: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
08d0: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
08e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
08f0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
0900: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
0910: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
0920: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
0930: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
0940: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20  atibility only. 
0950: 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69   Application wri
0960: 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61  ters should be a
0970: 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70  ware that.** exp
0980: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0990: 61 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74  aces are subject
09a0: 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f   to change in po
09b0: 69 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a  int releases..**
09c0: 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73  .** These macros
09d0: 20 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65   used to resolve
09e0: 20 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64   to various kind
09f0: 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61  s of compiler ma
0a00: 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c  gic that.** woul
0a10: 64 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69  d generate warni
0a20: 6e 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e  ng messages when
0a30: 20 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e   they were used.
0a40: 20 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f    But that.** co
0a50: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64  mpiler magic end
0a60: 65 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67  ed up generating
0a70: 20 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f   such a flurry o
0a80: 66 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a  f bug reports.**
0a90: 20 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61   that we have ta
0aa0: 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61  ken it all out a
0ab0: 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20  nd gone back to 
0ac0: 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20  using simple.** 
0ad0: 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a  noop macros..*/.
0ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
0af0: 45 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e  EPRECATED.#defin
0b00: 65 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  e SQLITE_EXPERIM
0b10: 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73  ENTAL../*.** Ens
0b20: 75 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c  ure these symbol
0b30: 73 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e  s were not defin
0b40: 65 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69  ed by some previ
0b50: 6f 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e  ous header file.
0b60: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
0b70: 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65  E_VERSION.# unde
0b80: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b90: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53  .#endif.#ifdef S
0ba0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0bb0: 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c  MBER.# undef SQL
0bc0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bd0: 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  ER.#endif../*.**
0be0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
0bf0: 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  le-Time Library 
0c00: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
0c10: 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  **.** ^(The [SQL
0c20: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70  ITE_VERSION] C p
0c30: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
0c40: 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  o in the sqlite3
0c50: 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61  .h header.** eva
0c60: 6c 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69  luates to a stri
0c70: 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20  ng literal that 
0c80: 69 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65  is the SQLite ve
0c90: 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20  rsion in the.** 
0ca0: 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77  format "X.Y.Z" w
0cb0: 68 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61  here X is the ma
0cc0: 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  jor version numb
0cd0: 65 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72  er (always 3 for
0ce0: 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64  .** SQLite3) and
0cf0: 20 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20   Y is the minor 
0d00: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61  version number a
0d10: 6e 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65  nd Z is the rele
0d20: 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a  ase number.)^.**
0d30: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
0d40: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43  ERSION_NUMBER] C
0d50: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
0d60: 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20  cro resolves to 
0d70: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69  an integer.** wi
0d80: 74 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a  th the value (X*
0d90: 31 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30  1000000 + Y*1000
0da0: 20 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59   + Z) where X, Y
0db0: 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20  , and Z are the 
0dc0: 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  same.** numbers 
0dd0: 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f  used in [SQLITE_
0de0: 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54  VERSION].)^.** T
0df0: 68 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  he SQLITE_VERSIO
0e00: 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79  N_NUMBER for any
0e10: 20 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f   given release o
0e20: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  f SQLite will al
0e30: 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20  so.** be larger 
0e40: 74 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65  than the release
0e50: 20 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69   from which it i
0e60: 73 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68  s derived.  Eith
0e70: 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  er Y will.** be 
0e80: 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e  held constant an
0e90: 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72  d Z will be incr
0ea0: 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20  emented or else 
0eb0: 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Y will be increm
0ec0: 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77  ented.** and Z w
0ed0: 69 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20  ill be reset to 
0ee0: 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63  zero..**.** Sinc
0ef0: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
0f00: 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  8] ([dateof:3.6.
0f10: 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c 69 74 65  18]), .** SQLite
0f20: 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 73   source code has
0f30: 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e 20   been stored in 
0f40: 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
0f50: 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69  http://www.fossi
0f60: 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73  l-scm.org/">Foss
0f70: 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  il configuration
0f80: 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73   management.** s
0f90: 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65  ystem</a>.  ^The
0fa0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0fb0: 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 65  D macro evaluate
0fc0: 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67  s to.** a string
0fd0: 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 65   which identifie
0fe0: 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  s a particular c
0ff0: 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74  heck-in of SQLit
1000: 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 20  e.** within its 
1010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
1020: 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e  nagement system.
1030: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
1040: 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e  URCE_ID.** strin
1050: 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  g contains the d
1060: 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 20  ate and time of 
1070: 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 54  the check-in (UT
1080: 43 29 20 61 6e 64 20 61 20 53 48 41 31 0a 2a 2a  C) and a SHA1.**
1090: 20 6f 72 20 53 48 41 33 2d 32 35 36 20 68 61 73   or SHA3-256 has
10a0: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
10b0: 73 6f 75 72 63 65 20 74 72 65 65 2e 20 20 49 66  source tree.  If
10c0: 20 74 68 65 20 73 6f 75 72 63 65 20 63 6f 64 65   the source code
10d0: 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 64 69   has.** been edi
10e0: 74 65 64 20 69 6e 20 61 6e 79 20 77 61 79 20 73  ted in any way s
10f0: 69 6e 63 65 20 69 74 20 77 61 73 20 6c 61 73 74  ince it was last
1100: 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 74 68 65   checked in, the
1110: 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a 20 66 6f  n the last.** fo
1120: 75 72 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  ur hexadecimal d
1130: 69 67 69 74 73 20 6f 66 20 74 68 65 20 68 61 73  igits of the has
1140: 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 66 69 65  h may be modifie
1150: 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
1160: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  o: [sqlite3_libv
1170: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73  ersion()],.** [s
1180: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1190: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71  n_number()], [sq
11a0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
11b0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65  ],.** [sqlite_ve
11c0: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
11d0: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
11e0: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
11f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20  LITE_VERSION    
1200: 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23      "--VERS--".#
1210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
1220: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56  RSION_NUMBER --V
1230: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a  ERSION-NUMBER--.
1240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1250: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d  OURCE_ID      "-
1260: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f  -SOURCE-ID--"../
1270: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1280: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1290: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a  Version Numbers.
12a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
12b0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c  ite3_version sql
12c0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a  ite3_sourceid.**
12d0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66  .** These interf
12e0: 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65  aces provide the
12f0: 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1300: 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45  n as the [SQLITE
1310: 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53  _VERSION],.** [S
1320: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1330: 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49  MBER], and [SQLI
1340: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
1350: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1360: 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61  ros.** but are a
1370: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1380: 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65  he library inste
1390: 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72  ad of the header
13a0: 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f   file.  ^(Cautio
13b0: 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72  us.** programmer
13c0: 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20  s might include 
13d0: 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
13e0: 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70  nts in their app
13f0: 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76  lication to.** v
1400: 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65  erify that value
1410: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1420: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
1430: 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20  atch the macros 
1440: 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72  in.** the header
1450: 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72  , and thus ensur
1460: 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69  e that the appli
1470: 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d  cation is.** com
1480: 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68  piled with match
1490: 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20  ing library and 
14a0: 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a  header files..**
14b0: 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
14c0: 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28  <pre>.** assert(
14d0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14e0: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51  ion_number()==SQ
14f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1500: 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74  BER );.** assert
1510: 28 20 73 74 72 6e 63 6d 70 28 73 71 6c 69 74 65  ( strncmp(sqlite
1520: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
1530: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30  ITE_SOURCE_ID,80
1540: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1550: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1560: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1570: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1580: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1590: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15a0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15b0: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
15c0: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
15d0: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
15e0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
15f0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
1600: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1610: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
1620: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1630: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1640: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1650: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1660: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1670: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1680: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1690: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
16a0: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
16b0: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
16c0: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
16d0: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
16e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
16f0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
1700: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
1710: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1720: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
1730: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1740: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1750: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1760: 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c  BER].  ^(The sql
1770: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20  ite3_sourceid() 
1780: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1790: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
17a0: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  o a string const
17b0: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20  ant whose value 
17c0: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74  is the same as t
17d0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53  he .** [SQLITE_S
17e0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
17f0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20  rocessor macro. 
1800: 20 45 78 63 65 70 74 20 69 66 20 53 51 4c 69 74   Except if SQLit
1810: 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73  e is built.** us
1820: 69 6e 67 20 61 6e 20 65 64 69 74 65 64 20 63 6f  ing an edited co
1830: 70 79 20 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67  py of [the amalg
1840: 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74  amation], then t
1850: 68 65 20 6c 61 73 74 20 66 6f 75 72 20 63 68 61  he last four cha
1860: 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68  racters.** of th
1870: 65 20 68 61 73 68 20 6d 69 67 68 74 20 62 65 20  e hash might be 
1880: 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b  different from [
1890: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
18a0: 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ].)^.**.** See a
18b0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
18c0: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
18d0: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
18e0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
18f0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1900: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1910: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1920: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1930: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1940: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1950: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1960: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1970: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1990: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
19a0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
19b0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
19c0: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
19d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19e0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
19f0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1a00: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1a10: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1a20: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1a30: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1a40: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1a50: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1a60: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1a70: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1a80: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1a90: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1aa0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1ab0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1ae0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
1af0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
1b00: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
1b10: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
1b20: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
1b30: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1b40: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1b50: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1b60: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1b70: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1b80: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1b90: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ba0: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1bb0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1bc0: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1bd0: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1be0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1bf0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1c00: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c10: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1c20: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1c30: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1c40: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1c50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c60: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1c70: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1c80: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1c90: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1ca0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1cb0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1cc0: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1cd0: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ce0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1cf0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1d00: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1d10: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1d20: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1d30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1d40: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1d50: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1d60: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1d70: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1d80: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1d90: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1da0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1db0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1dc0: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1dd0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1de0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1df0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1e00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1e10: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1e20: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1e30: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1e40: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1e50: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1e60: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1e70: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1e80: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1e90: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1ea0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1eb0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1ec0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1ed0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1ee0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1ef0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1f00: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1f10: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1f20: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1f30: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1f40: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1f50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1f60: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1f70: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1f80: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1f90: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1fa0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1fb0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fc0: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1fd0: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1fe0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1ff0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
2000: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
2010: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
2020: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
2030: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
2040: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
2050: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
2060: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
2070: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
2080: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
2090: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
20a0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
20b0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
20c0: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
20d0: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
20e0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
20f0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
2100: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
2110: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
2120: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
2130: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2150: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2160: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2170: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2180: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2190: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
21a0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
21b0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
21c0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
21d0: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
21e0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
21f0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
2200: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
2210: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
2220: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
2230: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2240: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2250: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2260: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2290: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
22a0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
22b0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
22c0: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
22d0: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
22e0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
22f0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
2300: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
2310: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
2320: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
2330: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2340: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2350: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2360: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2370: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2380: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2390: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
23a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
23b0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
23c0: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
23d0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
23e0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
23f0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
2400: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
2410: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
2420: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2430: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2440: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2450: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2460: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2470: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2480: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2490: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
24a0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
24b0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
24c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
24d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
24e0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
24f0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2500: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
2510: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
2520: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2530: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2540: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2550: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2560: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2570: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2580: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2590: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
25a0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
25b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
25c0: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
25d0: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
25e0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
25f0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
2600: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
2610: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
2620: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
2630: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2640: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2650: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2660: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2670: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2680: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2690: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
26a0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
26b0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
26c0: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
26d0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
26e0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
26f0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
2700: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
2710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2730: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2740: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2750: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2760: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2770: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2780: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2790: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
27a0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
27b0: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
27c0: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
27d0: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
27e0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
27f0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
2800: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2810: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
2820: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
2830: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2840: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2850: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2860: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2870: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2880: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2890: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
28a0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
28b0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
28c0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
28d0: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
28e0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
28f0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
2900: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
2910: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2920: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
2930: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2940: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2950: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2960: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2970: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2980: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2990: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
29a0: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
29b0: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
29c0: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
29d0: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
29e0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29f0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
2a00: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
2a10: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2a20: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
2a30: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2a40: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2a50: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2a60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2a70: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2a80: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2a90: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2aa0: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2ab0: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2ac0: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2ad0: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
2ae0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
2af0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
2b00: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
2b10: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2b20: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
2b30: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2b40: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2b50: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2b60: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2b70: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2b80: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2b90: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2ba0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2bb0: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2bc0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2bd0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2be0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2bf0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2c00: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2c10: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2c20: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2c30: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2c40: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2c50: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2c60: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2c70: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2c80: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2c90: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2ca0: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2cb0: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2cc0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2cd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ce0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2cf0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2d00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2d10: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2d20: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2d30: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2d40: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2d50: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2d60: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2d70: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2d80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2d90: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2da0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2db0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2dc0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2dd0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2de0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2df0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2e00: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2e10: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2e20: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2e30: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2e40: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2e50: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2e60: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2e70: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2e80: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2e90: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2ea0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2eb0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ec0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ed0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2ee0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2ef0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2f00: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2f10: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2f20: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2f30: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2f40: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2f50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2f60: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2f70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2f80: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2f90: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2fa0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2fb0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2fd0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2fe0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2ff0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
3000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
3010: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
3020: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
3030: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
3040: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
3050: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
3060: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
3070: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
3080: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
3090: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
30a0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
30b0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
30c0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
30d0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
30e0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
30f0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
3100: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
3110: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
3120: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
3130: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3140: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3150: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3160: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3170: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3180: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3190: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
31a0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
31b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
31c0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
31d0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
31e0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31f0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
3200: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
3210: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
3220: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
3230: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3240: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3250: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3260: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3270: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3280: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3290: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
32a0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32b0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
32c0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
32d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
32e0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
32f0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3300: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3310: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3320: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3330: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3340: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3350: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3360: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3370: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3380: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3390: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
33a0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
33b0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
33c0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
33d0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
33e0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
33f0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3400: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3410: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3420: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3440: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3450: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3460: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3470: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3480: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3490: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
34a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
34b0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
34c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
34d0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
34e0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
34f0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3500: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3510: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3520: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3530: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3540: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3550: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3560: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3570: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3580: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3590: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
35b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
35c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
35d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
35e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
35f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3600: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3610: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3620: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3630: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3640: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3650: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3660: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3670: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3680: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3690: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
36a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
36b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
36c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
36d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
36e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
36f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
3700: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
3710: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
3720: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
3730: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3740: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3750: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3760: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3770: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3780: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3790: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
37a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
37b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
37c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
37e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
37f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
3800: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
3810: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
3820: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3830: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3840: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3850: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3860: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3870: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3880: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3890: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
38a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
38b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
38c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
38d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
38e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
38f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
3900: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
3910: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
3920: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
3930: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3940: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3950: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3960: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3970: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3980: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3990: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
39a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
39b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
39c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
39d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
39e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
39f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
3a00: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
3a10: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
3a20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
3a30: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3a40: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3a50: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3a60: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3a70: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3a80: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3a90: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3aa0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3ab0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3ac0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3ad0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
3ae0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3af0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3b00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
3b10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
3b20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
3b30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3b40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3b50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3b60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3b70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3b80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3b90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3ba0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3bb0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3bc0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3bd0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3be0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3bf0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3c00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3c10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3c20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3c30: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3c40: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3c50: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3c60: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3c70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3c80: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3c90: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3ca0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3cb0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3cc0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3cd0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ce0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3cf0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3d00: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3d10: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3d20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3d30: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3d40: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3d50: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3d60: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3d70: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3d80: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3d90: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3da0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3db0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3dc0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3dd0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3de0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3df0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3e00: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3e10: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3e20: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3e30: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3e40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3e60: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3e70: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e80: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3e90: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3ea0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3eb0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3ec0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3ed0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ee0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3ef0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3f00: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3f10: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3f20: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3f30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3f40: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3f50: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3f60: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3f70: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3f80: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3f90: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3fa0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3fb0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3fc0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3fd0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3fe0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3ff0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
4000: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
4010: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
4020: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
4030: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
4040: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
4050: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
4060: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
4070: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
4080: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
4090: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
40a0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
40b0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
40c0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
40d0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
40e0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
40f0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
4100: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
4110: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
4120: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
4130: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4140: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4150: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4160: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4170: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4180: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4190: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
41a0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
41b0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
41c0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
41d0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
41e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
41f0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
4200: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
4210: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
4220: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
4230: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4240: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4250: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4260: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4270: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4280: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4290: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
42a0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
42b0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
42c0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
42d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
42e0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
42f0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4300: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4310: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4330: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4340: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4350: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4370: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4380: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4390: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
43a0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
43b0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
43c0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
43d0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
43e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
43f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4400: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4410: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4420: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4430: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4450: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4460: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4470: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4480: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4490: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
44a0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
44b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
44c0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
44d0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
44e0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
44f0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4500: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4510: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4520: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4530: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4540: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4550: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4560: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4570: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4580: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4590: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
45a0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
45b0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
45c0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
45d0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
45e0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
45f0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4610: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4620: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
4630: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4640: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4650: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4660: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4670: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4680: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4690: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
46a0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
46b0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
46c0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
46d0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
46e0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
46f0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4700: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4710: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4720: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4730: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4760: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4770: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4780: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4790: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
47a0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
47b0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
47c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
47d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
47e0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
47f0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4800: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4820: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4830: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4840: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4850: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4870: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4880: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4890: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
48a0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
48b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
48c0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
48d0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
48e0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
48f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4900: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4910: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4920: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4930: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4940: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4950: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4960: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4970: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4980: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4990: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
49a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
49b0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
49c0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
49d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
49e0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
49f0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4a00: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4a10: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4a30: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4a40: 2a 20 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f  * Internal use o
4a50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
4a60: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4a70: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4a80: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4a90: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4aa0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4ab0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4ac0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4ad0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4af0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4b00: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4b10: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4b20: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4b30: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4b40: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4b50: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4b60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b70: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4b80: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4b90: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4bc0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4bd0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4be0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4c00: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4c10: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4c20: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4c30: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4c40: 20 20 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20      24   /* Not 
4c50: 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
4c60: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4c70: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4c80: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4c90: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4ca0: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4cb0: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4cc0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4cd0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
4ce0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
4cf0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
4d00: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
4d10: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4d20: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4d30: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4d40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4d50: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4d60: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4d70: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4d90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4da0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4db0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4dc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4dd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4de0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4df0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4e00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4e10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4e20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4e30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4e40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4e50: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4e60: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4e70: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4e80: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4e90: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4ea0: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4eb0: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ec0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4ed0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4ee0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4ef0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4f00: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4f10: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4f20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4f30: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4f40: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4f50: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4f60: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4f70: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4f80: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4f90: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4fa0: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4fb0: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4fc0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4fd0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4fe0: 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33  .3.8 [dateof:3.3
4ff0: 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72  .8].** and later
5000: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70  ) include.** sup
5010: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f  port for additio
5020: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  nal result codes
5030: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f   that provide mo
5040: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f  re detailed info
5050: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74  rmation.** about
5060: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b   errors. These [
5070: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
5080: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c  codes] are enabl
5090: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a  ed or disabled.*
50a0: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62  * on a per datab
50b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
50c0: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a  asis using the.*
50d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  * [sqlite3_exten
50e0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
50f0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68  ()] API.  Or, th
5100: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20  e extended code 
5110: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20  for.** the most 
5120: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e  recent error can
5130: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69   be obtained usi
5140: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
5150: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
5160: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
5170: 51 4c 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53  QLITE_ERROR_MISS
5180: 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53  ING_COLLSEQ   (S
5190: 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31  QLITE_ERROR | (1
51a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
51b0: 4c 49 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59  LITE_ERROR_RETRY
51c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
51d0: 4c 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c  LITE_ERROR | (2<
51e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
51f0: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5200: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5210: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5220: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5230: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5240: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5250: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
5260: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5270: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
5280: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5290: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
52a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52b0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
52c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52d0: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
52e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52f0: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5300: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5310: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5330: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5340: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5350: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5370: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
5380: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5390: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
53f0: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5400: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5410: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5540: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5550: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55b0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55d0: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55f0: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5600: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5610: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5620: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5630: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5640: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5650: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
5660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5670: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
5680: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5690: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56b0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
56c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56d0: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
56e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56f0: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5700: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5710: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5720: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5730: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5740: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5750: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5760: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5770: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
5780: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5790: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
57a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57b0: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
57c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
57d0: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
57e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
57f0: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5800: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5810: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5830: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5850: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5870: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
5880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5890: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
58a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58b0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
58c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
58d0: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
58e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
58f0: 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20  _BEGIN_ATOMIC   
5900: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5910: 20 7c 20 28 32 39 3c 3c 38 29 29 0a 23 64 65 66   | (29<<8)).#def
5920: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5930: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20  _COMMIT_ATOMIC  
5940: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5950: 20 7c 20 28 33 30 3c 3c 38 29 29 0a 23 64 65 66   | (30<<8)).#def
5960: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5970: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
5980: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5990: 20 7c 20 28 33 31 3c 3c 38 29 29 0a 23 64 65 66   | (31<<8)).#def
59a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
59b0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
59c0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
59d0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
59f0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5a10: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5a30: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5a50: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5a60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5a70: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5a80: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5a90: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5aa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ab0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5ac0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5ad0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5b00: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5b10: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5b20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b30: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5b40: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5b50: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5b60: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5b70: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5b80: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5b90: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5ba0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5bb0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5bc0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5bd0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5be0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5bf0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5c00: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5c10: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5c20: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5c40: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5c60: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5c80: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5c90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5ca0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5cc0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e 49 54  EADONLY_CANTINIT
5cd0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5ce0: 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c 38 29  EADONLY | (5<<8)
5cf0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5d00: 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45 43 54  _READONLY_DIRECT
5d10: 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49 54 45  ORY      (SQLITE
5d20: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36 3c 3c  _READONLY | (6<<
5d30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d40: 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43  TE_ABORT_ROLLBAC
5d50: 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  K          (SQLI
5d60: 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38  TE_ABORT | (2<<8
5d70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45  E_CONSTRAINT_CHE
5d90: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  CK        (SQLIT
5da0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5db0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5dc0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5dd0: 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53  _COMMITHOOK   (S
5de0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5df0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5e00: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5e10: 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20  AINT_FOREIGNKEY 
5e20: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5e30: 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23  AINT | (3<<8)).#
5e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5e50: 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f  NSTRAINT_FUNCTIO
5e60: 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  N     (SQLITE_CO
5e70: 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38  NSTRAINT | (4<<8
5e80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5e90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54  E_CONSTRAINT_NOT
5ea0: 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54  NULL      (SQLIT
5eb0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5ec0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
5ed0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ee0: 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53  _PRIMARYKEY   (S
5ef0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5f00: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
5f10: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5f20: 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20  AINT_TRIGGER    
5f30: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5f40: 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23  AINT | (7<<8)).#
5f50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5f60: 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20  NSTRAINT_UNIQUE 
5f70: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5f80: 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38  NSTRAINT | (8<<8
5f90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5fa0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41  E_CONSTRAINT_VTA
5fb0: 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  B         (SQLIT
5fc0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5fd0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
5fe0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5ff0: 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53  _ROWID        (S
6000: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
6010: 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69   |(10<<8)).#defi
6020: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
6030: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20  _RECOVER_WAL    
6040: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45    (SQLITE_NOTICE
6050: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
6060: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
6070: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43  _RECOVER_ROLLBAC
6080: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  K (SQLITE_NOTICE
6090: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
60a0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
60b0: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20  G_AUTOINDEX     
60c0: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e    (SQLITE_WARNIN
60d0: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  G | (1<<8)).#def
60e0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f  ine SQLITE_AUTH_
60f0: 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20  USER            
6100: 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20     (SQLITE_AUTH 
6110: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
6120: 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44  e SQLITE_OK_LOAD
6130: 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20  _PERMANENTLY    
6140: 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31   (SQLITE_OK | (1
6150: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
6160: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
6170: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
6180: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
6190: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
61a0: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
61b0: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
61c0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
61d0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
61e0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
61f0: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
6200: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
6210: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6220: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
6230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6240: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
6250: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
6260: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6270: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6290: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
62a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
62b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
62c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
62d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
62e0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
62f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6300: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6310: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6320: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6330: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
6340: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
6350: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6370: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
6380: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6390: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
63a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63b0: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
63c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
63d0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
63e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
63f0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
6400: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
6410: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6420: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6440: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20  OPEN_MEMORY     
6450: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
6460: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6470: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6490: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
64a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
64b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
64c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
64d0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
64e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
64f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6510: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
6520: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
6530: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6550: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
6560: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
6570: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6590: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
65a0: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
65b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
65c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
65d0: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
65e0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
65f0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6610: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
6620: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
6630: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
6640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6650: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
6660: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
6670: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6680: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
66a0: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
66b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
66c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
66d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
66e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
66f0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
6700: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
6710: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6720: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6730: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6740: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
6750: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
6760: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
6770: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
6780: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6790: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
67a0: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
67b0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
67c0: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
67d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
67e0: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
67f0: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
6800: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
6810: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
6820: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
6830: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
6840: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
6850: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6860: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
6870: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
6880: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
6890: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  of these.** bit 
68a0: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
68b0: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
68c0: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
68d0: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
68e0: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
68f0: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
6900: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6910: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
6920: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
6930: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6940: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
6950: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
6960: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
6970: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6980: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6990: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
69a0: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
69b0: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
69c0: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
69d0: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
69e0: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
69f0: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
6a00: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
6a10: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
6a20: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
6a30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6a40: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
6a50: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
6a60: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
6a70: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
6a80: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
6a90: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
6aa0: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
6ab0: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
6ac0: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
6ad0: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
6ae0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
6af0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6b00: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
6b10: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
6b20: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
6b30: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
6b40: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
6b50: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
6b60: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6b70: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
6b80: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
6b90: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
6ba0: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
6bb0: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
6bc0: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
6bd0: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
6be0: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
6bf0: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
6c00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
6c10: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
6c20: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
6c30: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
6c40: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
6c50: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
6c60: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
6c70: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
6c80: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49  anged.  The SQLI
6c90: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
6ca0: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a  ABLE_WHEN_OPEN.*
6cb0: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73  * flag indicates
6cc0: 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e   that a file can
6cd0: 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77  not be deleted w
6ce0: 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a  hen open.  The.*
6cf0: 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  * SQLITE_IOCAP_I
6d00: 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e  MMUTABLE flag in
6d10: 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65  dicates that the
6d20: 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72   file is on.** r
6d30: 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61  ead-only media a
6d40: 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  nd cannot be cha
6d50: 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f  nged even by pro
6d60: 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65  cesses with.** e
6d70: 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67  levated privileg
6d80: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  es..**.** The SQ
6d90: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48  LITE_IOCAP_BATCH
6da0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6db0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
6dc0: 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66 69  underlying.** fi
6dd0: 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74  lesystem support
6de0: 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c 65  s doing multiple
6df0: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
6e00: 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68 65  s atomically whe
6e10: 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74 65  n those.** write
6e20: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6e30: 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b 53 51  bracketed by [SQ
6e40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e  LITE_FCNTL_BEGIN
6e50: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 61  _ATOMIC_WRITE] a
6e60: 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  nd.** [SQLITE_FC
6e70: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
6e80: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64 65  C_WRITE]..*/.#de
6e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ea0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
6eb0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6ec0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6ed0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6ee0: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6ef0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6f00: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6f10: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6f20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6f30: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6f40: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
6f50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6f60: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
6f70: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6f80: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
6f90: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
6fa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6fb0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
6fc0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6fd0: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6fe0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6ff0: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
7000: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
7010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
7020: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
7030: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7040: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
7050: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7060: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
7070: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
7080: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
7090: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
70a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
70b0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
70c0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
70d0: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
70e0: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
70f0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
7100: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
7110: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
7120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7130: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
7140: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
7150: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
7160: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
7170: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
7180: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23      0x00002000.#
7190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
71a0: 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43  CAP_BATCH_ATOMIC
71b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
71c0: 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  04000../*.** CAP
71d0: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b  I3REF: File Lock
71e0: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a  ing Levels.**.**
71f0: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65   SQLite uses one
7200: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65   of these intege
7210: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
7220: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65  second.** argume
7230: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d  nt to calls it m
7240: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63  akes to the xLoc
7250: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
7260: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ) methods.** of 
7270: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  an [sqlite3_io_m
7280: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a  ethods] object..
7290: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
72a0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20  E_LOCK_NONE     
72b0: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
72c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
72d0: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  D        1.#defi
72e0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  ne SQLITE_LOCK_R
72f0: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23  ESERVED      2.#
7300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
7310: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20  CK_PENDING      
7320: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
7330: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7340: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41       4../*.** CA
7350: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e  PI3REF: Synchron
7360: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61  ization Type Fla
7370: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51  gs.**.** When SQ
7380: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65  Lite invokes the
7390: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20   xSync() method 
73a0: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  of an.** [sqlite
73b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
73c0: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63  ject it uses a c
73d0: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
73e0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
73f0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
7400: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ond argument..**
7410: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c  .** When the SQL
7420: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7430: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20  Y flag is used, 
7440: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  it means that th
7450: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74  e.** sync operat
7460: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  ion only needs t
7470: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20  o flush data to 
7480: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49  mass storage.  I
7490: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  node.** informat
74a0: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  ion need not be 
74b0: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20  flushed. If the 
74c0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
74d0: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65  of the flag.** e
74e0: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
74f0: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65  _NORMAL, that me
7500: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61  ans to use norma
7510: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74  l fsync() semant
7520: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c  ics..** If the l
7530: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65  ower four bits e
7540: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43  qual SQLITE_SYNC
7550: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e  _FULL, that mean
7560: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20  s.** to use Mac 
7570: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
7580: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66  ync instead of f
7590: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f  sync()..**.** Do
75a0: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65   not confuse the
75b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
75c0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
75d0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a  YNC_FULL flags.*
75e0: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47  * with the [PRAG
75f0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7600: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47  NORMAL and [PRAG
7610: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d  MA synchronous]=
7620: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73  FULL.** settings
7630: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e  .  The [synchron
7640: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65  ous pragma] dete
7650: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c  rmines when call
7660: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e  s to the.** xSyn
7670: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63  c VFS method occ
7680: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75  ur and applies u
7690: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20  niformly across 
76a0: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a  all platforms..*
76b0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  * The SQLITE_SYN
76c0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
76d0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
76e0: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f  ags determine ho
76f0: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f  w.** energetic o
7700: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f  r rigorous or fo
7710: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20  rceful the sync 
7720: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61  operations are a
7730: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20  nd.** only make 
7740: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20  a difference on 
7750: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20  Mac OSX for the 
7760: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63  default SQLite c
7770: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70  ode..** (Third-p
7780: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65  arty VFS impleme
7790: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61  ntations might a
77a0: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73  lso make the dis
77b0: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77  tinction.** betw
77c0: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  een SQLITE_SYNC_
77d0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
77e0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74  E_SYNC_FULL, but
77f0: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70   among the.** op
7800: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20  erating systems 
7810: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74  natively support
7820: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e  ed by SQLite, on
7830: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61  ly Mac OSX.** ca
7840: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69  res about the di
7850: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64  fference.).*/.#d
7860: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7870: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20  C_NORMAL        
7880: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0x00002.#define 
7890: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
78a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
78b0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
78c0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20  _SYNC_DATAONLY  
78d0: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a      0x00010../*.
78e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
78f0: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46  Interface Open F
7900: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  ile Handle.**.**
7910: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   An [sqlite3_fil
7920: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  e] object repres
7930: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c  ents an open fil
7940: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71  e in the .** [sq
7950: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69  lite3_vfs | OS i
7960: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e  nterface layer].
7970: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20    Individual OS 
7980: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70  interface.** imp
7990: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
79a0: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62  l.** want to sub
79b0: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63  class this objec
79c0: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61  t by appending a
79d0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
79e0: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77  .** for their ow
79f0: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74  n use.  The pMet
7a00: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20  hods entry is a 
7a10: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
7a20: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
7a30: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  hods] object tha
7a40: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64  t defines method
7a50: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67  s for performing
7a60: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  .** I/O operatio
7a70: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66  ns on the open f
7a80: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ile..*/.typedef 
7a90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
7aa0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  ile sqlite3_file
7ab0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
7ac0: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20  _file {.  const 
7ad0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
7ae0: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68  o_methods *pMeth
7af0: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73  ods;  /* Methods
7b00: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c   for an open fil
7b10: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.};../*.** C
7b20: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7b30: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75  rface File Virtu
7b40: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63  al Methods Objec
7b50: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69  t.**.** Every fi
7b60: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65  le opened by the
7b70: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7b80: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75  pen] method popu
7b90: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c  lates an.** [sql
7ba0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7bb0: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d  t (or, more comm
7bc0: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73  only, a subclass
7bd0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
7be0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7bf0: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
7c00: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
7c10: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a  of this object..
7c20: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64  ** This object d
7c30: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f  efines the metho
7c40: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f  ds used to perfo
7c50: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61  rm various opera
7c60: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74  tions.** against
7c70: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72   the open file r
7c80: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68  epresented by th
7c90: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
7ca0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49   object..**.** I
7cb0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
7cc0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7cd0: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
7ce0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7cf0: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
7d00: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
7d10: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
7d20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
7d30: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
7d40: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
7d50: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69  ven if the [sqli
7d60: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72  te3_vfs.xOpen] r
7d70: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20  eported that it 
7d80: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20  failed.  The.** 
7d90: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76  only way to prev
7da0: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43  ent a call to xC
7db0: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  lose following a
7dc0: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33   failed [sqlite3
7dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69  _vfs.xOpen].** i
7de0: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  s for the [sqlit
7df0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f  e3_vfs.xOpen] to
7e00: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
7e10: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7e20: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c  lement.** to NUL
7e30: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  L..**.** The fla
7e40: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
7e50: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20  Sync may be one 
7e60: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  of [SQLITE_SYNC_
7e70: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53  NORMAL] or.** [S
7e80: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d  QLITE_SYNC_FULL]
7e90: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f  .  The first cho
7ea0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61  ice is the norma
7eb0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68  l fsync()..** Th
7ec0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20  e second choice 
7ed0: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74  is a Mac OS X st
7ee0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54  yle fullsync.  T
7ef0: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  he [SQLITE_SYNC_
7f00: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61  DATAONLY].** fla
7f10: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e  g may be ORed in
7f20: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
7f30: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20  t only the data 
7f40: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61  of the file.** a
7f50: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65  nd not its inode
7f60: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e   needs to be syn
7f70: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ced..**.** The i
7f80: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f  nteger values to
7f90: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
7fa0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f  lock() are one o
7fb0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  f.** <ul>.** <li
7fc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  > [SQLITE_LOCK_N
7fd0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ONE],.** <li> [S
7fe0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
7ff0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
8000: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8010: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  D],.** <li> [SQL
8020: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
8030: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
8040: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8050: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  SIVE]..** </ul>.
8060: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65  ** xLock() incre
8070: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78  ases the lock. x
8080: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73  Unlock() decreas
8090: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20  es the lock..** 
80a0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76  The xCheckReserv
80b0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20  edLock() method 
80c0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61  checks whether a
80d0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ny database conn
80e0: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65  ection,.** eithe
80f0: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73  r in this proces
8100: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68  s or in some oth
8110: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68  er process, is h
8120: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45  olding a RESERVE
8130: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f  D,.** PENDING, o
8140: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b  r EXCLUSIVE lock
8150: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49   on the file.  I
8160: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a  t returns true.*
8170: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b  * if such a lock
8180: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73   exists and fals
8190: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  e otherwise..**.
81a0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74  ** The xFileCont
81b0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20  rol() method is 
81c0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66  a generic interf
81d0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  ace that allows 
81e0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d  custom.** VFS im
81f0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f  plementations to
8200: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f   directly contro
8210: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75  l an open file u
8220: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
8230: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8240: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  l()] interface. 
8250: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22   The second "op"
8260: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a   argument is an.
8270: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64  ** integer opcod
8280: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72  e.  The third ar
8290: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65  gument is a gene
82a0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65  ric pointer inte
82b0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74  nded to.** point
82c0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20   to a structure 
82d0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e  that may contain
82e0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70   arguments or sp
82f0: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a  ace in which to.
8300: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20  ** write return 
8310: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69  values.  Potenti
8320: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c  al uses for xFil
8330: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74  eControl() might
8340: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   be.** functions
8350: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b   to enable block
8360: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74  ing locks with t
8370: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e  imeouts, to chan
8380: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e  ge the.** lockin
8390: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20  g strategy (for 
83a0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64  example to use d
83b0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20  ot-file locks), 
83c0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62  to inquire.** ab
83d0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f  out the status o
83e0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20  f a lock, or to 
83f0: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b  break stale lock
8400: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a  s.  The SQLite.*
8410: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20  * core reserves 
8420: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73  all opcodes less
8430: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74   than 100 for it
8440: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20  s own use..** A 
8450: 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  [file control op
8460: 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20  codes | list of 
8470: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68  opcodes] less th
8480: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61  an 100 is availa
8490: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ble..** Applicat
84a0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65  ions that define
84b0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43   a custom xFileC
84c0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68  ontrol method sh
84d0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73  ould use opcodes
84e0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e  .** greater than
84f0: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f   100 to avoid co
8500: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d  nflicts.  VFS im
8510: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
8520: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
8530: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
8540: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f   for file contro
8550: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74  l opcodes that t
8560: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65  hey do not.** re
8570: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54  cognize..**.** T
8580: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29  he xSectorSize()
8590: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
85a0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  the sector size 
85b0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65  of the.** device
85c0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20   that underlies 
85d0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73  the file.  The s
85e0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68  ector size is th
85f0: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69  e.** minimum wri
8600: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70  te that can be p
8610: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74  erformed without
8620: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f   disturbing.** o
8630: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68  ther bytes in th
8640: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65  e file.  The xDe
8650: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
8660: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ics().** method 
8670: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65  returns a bit ve
8680: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20  ctor describing 
8690: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65  behaviors of the
86a0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64  .** underlying d
86b0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  evice:.**.** <ul
86c0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
86d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a  E_IOCAP_ATOMIC].
86e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
86f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d  IOCAP_ATOMIC512]
8700: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8710: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d  _IOCAP_ATOMIC1K]
8720: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8730: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d  _IOCAP_ATOMIC2K]
8740: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8750: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d  _IOCAP_ATOMIC4K]
8760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8770: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d  _IOCAP_ATOMIC8K]
8780: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8790: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
87a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
87b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
87c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
87d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
87e0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
87f0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
8800: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  PPEND].** <li> [
8810: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
8820: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  UENTIAL].** <li>
8830: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55   [SQLITE_IOCAP_U
8840: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
8850: 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OPEN].** <li> [S
8860: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
8870: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
8880: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8890: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
88a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
88b0: 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54  E_IOCAP_BATCH_AT
88c0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  OMIC].** </ul>.*
88d0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
88e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
88f0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8900: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
8910: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
8920: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
8930: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
8940: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
8950: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
8960: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
8970: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
8980: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
8990: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
89a0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
89b0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
89c0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
89d0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
89e0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
89f0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
8a00: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
8a10: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
8a20: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
8a30: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
8a40: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
8a50: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
8a60: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
8a70: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
8a80: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
8a90: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8aa0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
8ab0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
8ac0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
8ad0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
8ae0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
8af0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
8b00: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
8b10: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
8b20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
8b30: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
8b40: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
8b50: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
8b60: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
8b70: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
8b80: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
8b90: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
8ba0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8bb0: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
8bc0: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
8bd0: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
8be0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8bf0: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
8c00: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
8c10: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
8c20: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
8c30: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8c40: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
8c50: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
8c60: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8c70: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
8c80: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
8c90: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
8ca0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8cb0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
8cc0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
8cd0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
8ce0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
8cf0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
8d00: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
8d10: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
8d20: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8d30: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8d40: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
8d50: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8d60: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
8d70: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
8d80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8d90: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
8da0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
8db0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8dc0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
8dd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
8de0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8df0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
8e00: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
8e10: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8e20: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
8e30: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
8e40: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
8e50: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8e60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
8e70: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8e80: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
8e90: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
8ea0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
8eb0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
8ec0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8ed0: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
8ee0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
8ef0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8f00: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
8f10: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
8f20: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
8f30: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
8f40: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
8f50: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
8f60: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
8f70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8f80: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
8f90: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8fa0: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
8fb0: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
8fc0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8fd0: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
8fe0: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
8ff0: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
9000: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
9010: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
9020: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65  2 */.  int (*xFe
9030: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
9040: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
9050: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d  4 iOfst, int iAm
9060: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20  t, void **pp);. 
9070: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29   int (*xUnfetch)
9080: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
9090: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
90a0: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20  fst, void *p);. 
90b0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
90c0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
90d0: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f  version 3 */.  /
90e0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
90f0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
9100: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
9110: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
9120: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
9130: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
9140: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59  l Opcodes.** KEY
9150: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e  WORDS: {file con
9160: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66  trol opcodes} {f
9170: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
9180: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  de}.**.** These 
9190: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
91a0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
91b0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
91c0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
91d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
91e0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
91f0: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
9200: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9210: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
9220: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e..**.** <ul>.**
9230: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9240: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a  NTL_LOCKSTATE]].
9250: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9260: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
9270: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
9280: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
9290: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
92a0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
92b0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
92c0: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
92d0: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
92e0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
92f0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
9300: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
9310: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
9320: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
9330: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
9340: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
9350: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
9360: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
9370: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
9380: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
9390: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
93a0: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
93b0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
93c0: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c  sting and is onl
93d0: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e  y available when
93e0: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54   the SQLITE_TEST
93f0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
9400: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
9410: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9420: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
9430: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
9440: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9450: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
9460: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
9470: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
9480: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
9490: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
94a0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
94b0: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
94c0: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
94d0: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
94e0: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
94f0: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
9500: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
9510: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
9520: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
9530: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
9540: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
9550: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
9560: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
9570: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
9580: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
9590: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
95a0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
95b0: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
95c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
95d0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
95e0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
95f0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9600: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
9610: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
9620: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
9630: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
9640: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
9650: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
9660: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
9670: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
9680: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
9690: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
96a0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
96b0: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
96c0: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
96d0: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
96e0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
96f0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
9700: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
9710: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
9720: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
9730: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
9740: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
9750: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
9760: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
9770: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
9780: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
9790: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
97a0: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
97b0: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
97c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
97d0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
97e0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
97f0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
9800: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
9810: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
9820: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
9830: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9840: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
9850: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
9860: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
9870: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9880: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
9890: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
98a0: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
98b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
98c0: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
98d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
98e0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
98f0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
9900: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
9910: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
9920: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
9930: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9940: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a  iated with the j
9950: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74  ournal file (eit
9960: 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c  her.** the [roll
9970: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72  back journal] or
9980: 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61   the [write-ahea
9990: 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61  d log]) for a pa
99a0: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
99b0: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
99c0: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
99d0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
99e0: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
99f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9a00: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
9a10: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
9a20: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
9a30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9a40: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
9a50: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
9a60: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9a70: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9a80: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
9a90: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9aa0: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9ab0: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9ac0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9ad0: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
9ae0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
9af0: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
9b00: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
9b10: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
9b20: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
9b30: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
9b40: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
9b50: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9b60: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9b70: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9b80: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
9b90: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9ba0: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9bb0: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9bc0: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9bd0: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
9be0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9bf0: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
9c00: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
9c10: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
9c20: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
9c30: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
9c40: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
9c50: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9c60: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9c70: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9c80: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
9c90: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9ca0: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9cb0: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9cc0: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9cd0: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
9ce0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9cf0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
9d00: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
9d10: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9d20: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9d30: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9d40: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9d50: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9d60: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9d70: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9d80: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9d90: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9da0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9db0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9dc0: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9dd0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9de0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9df0: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
9e00: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9e10: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
9e20: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
9e30: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
9e40: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
9e50: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9e60: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9e70: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9e80: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9e90: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9ea0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9eb0: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9ec0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9ed0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9ee0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9ef0: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
9f00: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9f10: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9f20: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9f30: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9f40: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
9f50: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9f60: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9f70: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9f80: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9f90: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9fa0: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9fb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9fc0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9fd0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9fe0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9ff0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
a000: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
a010: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
a020: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
a030: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
a040: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
a050: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
a060: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
a070: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
a080: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
a090: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
a0a0: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
a0b0: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
a0c0: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
a0d0: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
a0e0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
a0f0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
a100: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
a110: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
a120: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
a130: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
a140: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
a150: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
a160: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
a170: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
a180: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
a190: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
a1a0: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
a1b0: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
a1c0: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
a1d0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
a1e0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
a1f0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
a200: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
a210: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
a220: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
a230: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
a240: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
a250: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
a260: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a270: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
a280: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
a290: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
a2a0: 20 69 73 20 74 68 65 20 6e 65 77 20 72 65 74 72   is the new retr
a2b0: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
a2c0: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
a2d0: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
a2e0: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
a2f0: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
a300: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
a310: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
a320: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
a330: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
a340: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
a350: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
a360: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
a370: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
a380: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
a390: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
a3a0: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
a3b0: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
a3c0: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
a3d0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a3e0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
a3f0: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
a400: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
a410: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
a420: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
a430: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
a440: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
a450: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
a460: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
a470: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
a480: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
a490: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
a4a0: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a4b0: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
a4c0: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
a4d0: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
a4e0: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
a4f0: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
a500: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
a510: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
a520: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
a530: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
a540: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
a550: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
a560: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
a570: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
a580: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
a590: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
a5a0: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
a5b0: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
a5c0: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
a5d0: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
a5e0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
a5f0: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
a600: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
a610: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
a620: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
a630: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
a640: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
a650: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
a660: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
a670: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
a680: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
a690: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
a6a0: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
a6b0: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
a6c0: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
a6d0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
a6e0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
a6f0: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
a700: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
a710: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
a720: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
a730: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a740: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a750: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a760: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a770: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
a780: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
a790: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a7a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
a7b0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
a7c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a7d0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a7e0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a7f0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
a800: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
a810: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
a820: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
a830: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
a840: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
a850: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
a860: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
a870: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
a880: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
a890: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
a8a0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
a8b0: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
a8c0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a8d0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a8e0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a8f0: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a900: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a910: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
a920: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
a930: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
a940: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
a950: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
a960: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
a970: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
a980: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
a990: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
a9a0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
a9b0: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
a9c0: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
a9d0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a9e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a9f0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
aa00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
aa10: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
aa20: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
aa30: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
aa40: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
aa50: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
aa60: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
aa70: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
aa80: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
aa90: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
aaa0: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
aab0: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
aac0: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
aad0: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
aae0: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
aaf0: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
ab00: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
ab10: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ab20: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
ab30: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ab40: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
ab50: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
ab60: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
ab70: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
ab80: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
ab90: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
aba0: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
abb0: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
abc0: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
abd0: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
abe0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
abf0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
ac00: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
ac10: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
ac20: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
ac30: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
ac40: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
ac50: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
ac60: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
ac70: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
ac80: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
ac90: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
aca0: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
acb0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
acc0: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
acd0: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
ace0: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
acf0: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
ad00: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
ad10: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
ad20: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
ad30: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
ad40: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
ad50: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
ad60: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
ad70: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
ad80: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
ad90: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
ada0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
adb0: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
adc0: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
add0: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
ade0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
adf0: 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  VFS_POINTER]].**
ae00: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
ae10: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d  NTL_VFS_POINTER]
ae20: 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20   opcode finds a 
ae30: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74  pointer to the t
ae40: 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53  op-level.** [VFS
ae50: 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e  es] currently in
ae60: 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67   use.  ^(The arg
ae70: 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71  ument X in.** sq
ae80: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
ae90: 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e  ol(db,SQLITE_FCN
aea0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58  TL_VFS_POINTER,X
aeb0: 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20  ) must be.** of 
aec0: 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76  type "[sqlite3_v
aed0: 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f  fs] **".  This o
aee0: 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20  pcodes will set 
aef0: 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74  *X.** to a point
af00: 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65  er to the top-le
af10: 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57  vel VFS.)^.** ^W
af20: 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75  hen there are mu
af30: 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73  ltiple VFS shims
af40: 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74   in the stack, t
af50: 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73  his opcode finds
af60: 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f   the.** upper-mo
af70: 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a  st shim only..**
af80: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
af90: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
afa0: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
afb0: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
afc0: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
afd0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
afe0: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
aff0: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
b000: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
b010: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
b020: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
b030: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
b040: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
b050: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
b060: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
b070: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
b080: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
b090: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
b0a0: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
b0b0: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
b0c0: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
b0d0: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
b0e0: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
b0f0: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
b100: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
b110: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
b120: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
b130: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
b140: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
b150: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
b160: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
b170: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
b180: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
b190: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
b1a0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
b1b0: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
b1c0: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
b1d0: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
b1e0: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
b1f0: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
b200: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
b210: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
b220: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
b230: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
b240: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
b250: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
b260: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
b270: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
b280: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
b290: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
b2a0: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
b2b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b2c0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
b2d0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
b2e0: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
b2f0: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
b300: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
b310: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
b320: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b330: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
b340: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
b350: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
b360: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
b370: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
b380: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
b390: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
b3a0: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
b3b0: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
b3c0: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
b3d0: 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73  statement if res
b3e0: 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55  ult string is NU
b3f0: 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75  LL, or that retu
b400: 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66  rns a copy.** of
b410: 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69   the result stri
b420: 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ng if the string
b430: 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a   is non-NULL..**
b440: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
b450: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
b460: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
b470: 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c  rns.** any resul
b480: 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61  t code other tha
b490: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  n [SQLITE_OK] or
b4a0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
b4b0: 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  D], that means.*
b4c0: 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65  * that the VFS e
b4d0: 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72  ncountered an er
b4e0: 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69  ror while handli
b4f0: 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20  ng the [PRAGMA] 
b500: 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  and the.** compi
b510: 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52  lation of the PR
b520: 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20  AGMA fails with 
b530: 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20  an error.  ^The 
b540: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b550: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
b560: 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20  ntrol occurs at 
b570: 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
b580: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
b590: 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73  t analysis and s
b5a0: 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20  o.** it is able 
b5b0: 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c  to override buil
b5c0: 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74  t-in [PRAGMA] st
b5d0: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
b5e0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b5f0: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d  TL_BUSYHANDLER]]
b600: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
b610: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
b620: 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  ER].** file-cont
b630: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  rol may be invok
b640: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20  ed by SQLite on 
b650: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
b660: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72  e handle.** shor
b670: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20  tly after it is 
b680: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
b690: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73  to provide a cus
b6a0: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63  tom VFS with acc
b6b0: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  ess.** to the co
b6c0: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68  nnections busy-h
b6d0: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  andler callback.
b6e0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b6f0: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a   of type (void *
b700: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79  *).** - an array
b710: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29   of two (void *)
b720: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72   values. The fir
b730: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75  st (void *) actu
b740: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74  ally points.** t
b750: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
b760: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f  type (int (*)(vo
b770: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72  id *)). In order
b780: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63   to invoke the c
b790: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75  onnections.** bu
b7a0: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73  sy-handler, this
b7b0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
b7c0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
b7d0: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69   the second (voi
b7e0: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61  d *) in.** the a
b7f0: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79  rray as the only
b800: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74   argument. If it
b810: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
b820: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72  o, then the oper
b830: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
b840: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69  be retried. If i
b850: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  t returns zero, 
b860: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73  the custom VFS s
b870: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68  hould abandon th
b880: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65  e.** current ope
b890: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ration..**.** <l
b8a0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b8b0: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a  _TEMPFILENAME]].
b8c0: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20  ** ^Application 
b8d0: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b  can invoke the [
b8e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
b8f0: 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d  PFILENAME] file-
b900: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61  control.** to ha
b910: 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61  ve SQLite genera
b920: 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  te a.** temporar
b930: 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67  y filename using
b940: 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
b950: 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c  thm that is foll
b960: 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65  owed to generate
b970: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69  .** temporary fi
b980: 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50  lenames for TEMP
b990: 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65   tables and othe
b9a0: 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e  r internal uses.
b9b0: 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e    The.** argumen
b9c0: 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68  t should be a ch
b9d0: 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  ar** which will 
b9e0: 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  be filled with t
b9f0: 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77  he filename.** w
ba00: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
ba10: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
ba20: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
ba30: 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72  ()].  The caller
ba40: 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b   should.** invok
ba50: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
ba60: 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74  )] on the result
ba70: 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f   to avoid a memo
ba80: 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c  ry leak..**.** <
ba90: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
baa0: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  L_MMAP_SIZE]].**
bab0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
bac0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
bad0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
bae0: 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73  ed to query or s
baf0: 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75  et the.** maximu
bb00: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
bb10: 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75  s that will be u
bb20: 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d  sed for memory-m
bb30: 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68  apped I/O..** Th
bb40: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
bb50: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
bb60: 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74  ue of type sqlit
bb70: 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a  e3_int64 that.**
bb80: 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20   is an advisory 
bb90: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
bba0: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  f bytes in the f
bbb0: 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61  ile to memory ma
bbc0: 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74  p.  The.** point
bbd0: 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  er is overwritte
bbe0: 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76  n with the old v
bbf0: 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74  alue.  The limit
bc00: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
bc10: 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  if.** the value 
bc20: 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74  originally point
bc30: 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76  ed to is negativ
bc40: 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75  e, and so the cu
bc50: 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20  rrent limit .** 
bc60: 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62  can be queried b
bc70: 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70  y passing in a p
bc80: 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61  ointer to a nega
bc90: 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68  tive number.  Th
bca0: 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  is.** file-contr
bcb0: 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72  ol is used inter
bcc0: 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65  nally to impleme
bcd0: 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  nt [PRAGMA mmap_
bce0: 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  size]..**.** <li
bcf0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bd00: 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  TRACE]].** The [
bd10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
bd20: 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  CE] file control
bd30: 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f   provides adviso
bd40: 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ry information.*
bd50: 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f  * to the VFS abo
bd60: 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68  ut what the high
bd70: 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65  er layers of the
bd80: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72   SQLite stack ar
bd90: 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73  e doing..** This
bda0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
bdb0: 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46   used by some VF
bdc0: 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69  S activity traci
bdd0: 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54  ng [shims]..** T
bde0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
bdf0: 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
be00: 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72   string.  Higher
be10: 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a   layers in the.*
be20: 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d  * SQLite stack m
be30: 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74  ay generate inst
be40: 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69  ances of this fi
be50: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a  le control if.**
be60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
be70: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f  _FCNTL_TRACE] co
be80: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
be90: 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
bea0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
beb0: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
bec0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
bed0: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
bee0: 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  D] file control 
bef0: 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61  interprets its a
bf00: 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20  rgument as a.** 
bf10: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
bf20: 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69  teger and it wri
bf30: 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  tes a boolean in
bf40: 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
bf50: 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20  depending.** on 
bf60: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
bf70: 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e  he file has been
bf80: 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c   renamed, moved,
bf90: 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63   or deleted sinc
bfa0: 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73  e it.** was firs
bfb0: 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  t opened..**.** 
bfc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bfd0: 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e  TL_WIN32_GET_HAN
bfe0: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
bff0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c000: 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _GET_HANDLE] opc
c010: 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ode can be used 
c020: 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a  to obtain the.**
c030: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69   underlying nati
c040: 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61  ve file handle a
c050: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
c060: 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54   file handle.  T
c070: 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74  his file.** cont
c080: 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69  rol interprets i
c090: 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61  ts argument as a
c0a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61   pointer to a na
c0b0: 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  tive file handle
c0c0: 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74   and.** writes t
c0d0: 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c  he resulting val
c0e0: 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ue there..**.** 
c0f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c100: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
c110: 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  DLE]].** The [SQ
c120: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c130: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63  _SET_HANDLE] opc
c140: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
c150: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
c160: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
c170: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
c180: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61  ol method to swa
c190: 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c  p the file handl
c1a0: 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a  e with the one.*
c1b0: 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
c1c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
c1d0: 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c  t.  This capabil
c1e0: 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69  ity is used duri
c1f0: 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e  ng testing.** an
c200: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
c210: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
c220: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73  n SQLITE_TEST is
c230: 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
c240: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
c250: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a  TL_WAL_BLOCK]].*
c260: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c270: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69  NTL_WAL_BLOCK] i
c280: 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68  s a signal to th
c290: 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74  e VFS layer that
c2a0: 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20   it might.** be 
c2b0: 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20  advantageous to 
c2c0: 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78  block on the nex
c2d0: 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68  t WAL lock if th
c2e0: 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d  e lock is not im
c2f0: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61  mediately.** ava
c300: 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c  ilable.  The WAL
c310: 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65   subsystem issue
c320: 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75  s this signal du
c330: 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72  ring rare.** cir
c340: 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72  cumstances in or
c350: 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f  der to fix a pro
c360: 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69  blem with priori
c370: 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  ty inversion..**
c380: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
c390: 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d  ould <em>not</em
c3a0: 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d  > use this file-
c3b0: 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c  control..**.** <
c3c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c3d0: 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68  L_ZIPVFS]].** Th
c3e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c3f0: 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69  ZIPVFS] opcode i
c400: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
c410: 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c   zipvfs only. Al
c420: 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73  l other.** VFS s
c430: 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c  hould return SQL
c440: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72  ITE_NOTFOUND for
c450: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a   this opcode..**
c460: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c470: 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20  _FCNTL_RBU]].** 
c480: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
c490: 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73  L_RBU] opcode is
c4a0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
c4b0: 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
c4c0: 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52  used by.** the R
c4d0: 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c  BU extension onl
c4e0: 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46  y.  All other VF
c4f0: 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  S should return 
c500: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
c510: 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f  for.** this opco
c520: 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  de.  .**.** <li>
c530: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  [[SQLITE_FCNTL_B
c540: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54  EGIN_ATOMIC_WRIT
c550: 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53  E]].** If the [S
c560: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49  QLITE_FCNTL_BEGI
c570: 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20  N_ATOMIC_WRITE] 
c580: 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73 20 53  opcode returns S
c590: 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a  QLITE_OK, then.*
c5a0: 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72  * the file descr
c5b0: 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65 64 20  iptor is placed 
c5c0: 69 6e 20 22 62 61 74 63 68 20 77 72 69 74 65 20  in "batch write 
c5d0: 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a 20  mode", which.** 
c5e0: 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73 65 71  means all subseq
c5f0: 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61  uent write opera
c600: 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64 65  tions will be de
c610: 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e 65 0a  ferred and done.
c620: 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61 74  ** atomically at
c630: 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c 49 54   the next [SQLIT
c640: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41  E_FCNTL_COMMIT_A
c650: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20 53  TOMIC_WRITE].  S
c660: 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20 64  ystems.** that d
c670: 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 62 61  o not support ba
c680: 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69 74 65  tch atomic write
c690: 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  s will return SQ
c6a0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a  LITE_NOTFOUND..*
c6b0: 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 73  * ^Following a s
c6c0: 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49 54 45  uccessful SQLITE
c6d0: 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f  _FCNTL_BEGIN_ATO
c6e0: 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20 70 72  MIC_WRITE and pr
c6f0: 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6c  ior to.** the cl
c700: 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 43  osing [SQLITE_FC
c710: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49  NTL_COMMIT_ATOMI
c720: 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b  C_WRITE] or.** [
c730: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c  SQLITE_FCNTL_ROL
c740: 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49  LBACK_ATOMIC_WRI
c750: 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  TE], SQLite will
c760: 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53 20   make.** no VFS 
c770: 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 73 20  interface calls 
c780: 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c  on the same [sql
c790: 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65 20  ite3_file] file 
c7a0: 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65 78  descriptor.** ex
c7b0: 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73 20 74  cept for calls t
c7c0: 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d 65 74  o the xWrite met
c7d0: 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46 69 6c  hod and the xFil
c7e0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
c7f0: 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ** with [SQLITE_
c800: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
c810: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c820: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
c830: 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d  T_ATOMIC_WRITE]]
c840: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c850: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f  FCNTL_COMMIT_ATO
c860: 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64  MIC_WRITE] opcod
c870: 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69  e causes all wri
c880: 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73  te.** operations
c890: 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69   since the previ
c8a0: 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63  ous successful c
c8b0: 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49  all to .** [SQLI
c8c0: 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41  TE_FCNTL_BEGIN_A
c8d0: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20  TOMIC_WRITE] to 
c8e0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61 74 6f  be performed ato
c8f0: 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73  mically..** This
c900: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
c910: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
c920: 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
c930: 20 74 68 65 20 77 72 69 74 65 73 20 77 65 72 65   the writes were
c940: 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d 65  .** all performe
c950: 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61  d successfully a
c960: 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63 6f 6d  nd have been com
c970: 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73 69 73  mitted to persis
c980: 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a 2a  tent storage..**
c990: 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
c9a0: 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
c9b0: 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 2c  t is successful,
c9c0: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   this file contr
c9d0: 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65 20  ol takes.** the 
c9e0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20  file descriptor 
c9f0: 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69  out of batch wri
ca00: 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61 74 20  te mode so that 
ca10: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
ca20: 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f  * write operatio
ca30: 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65  ns are independe
ca40: 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  nt..** ^SQLite w
ca50: 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
ca60: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
ca70: 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54  MMIT_ATOMIC_WRIT
ca80: 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70  E without.** a p
ca90: 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
caa0: 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f  call to [SQLITE_
cab0: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
cac0: 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a  IC_WRITE]..**.**
cad0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
cae0: 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f  NTL_ROLLBACK_ATO
caf0: 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54  MIC_WRITE]].** T
cb00: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
cb10: 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43  _ROLLBACK_ATOMIC
cb20: 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63  _WRITE] opcode c
cb30: 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a  auses all write.
cb40: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69  ** operations si
cb50: 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75 73  nce the previous
cb60: 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
cb70: 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   to .** [SQLITE_
cb80: 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d  FCNTL_BEGIN_ATOM
cb90: 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20  IC_WRITE] to be 
cba0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20  rolled back..** 
cbb0: 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72  ^This file contr
cbc0: 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66 69 6c  ol takes the fil
cbd0: 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74  e descriptor out
cbe0: 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65 20   of batch write 
cbf0: 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74 20  mode.** so that 
cc00: 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77  all subsequent w
cc10: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  rite operations 
cc20: 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e  are independent.
cc30: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
cc40: 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51   never invoke SQ
cc50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42  LITE_FCNTL_ROLLB
cc60: 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  ACK_ATOMIC_WRITE
cc70: 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72   without.** a pr
cc80: 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
cc90: 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46  all to [SQLITE_F
cca0: 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49  CNTL_BEGIN_ATOMI
ccb0: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20  C_WRITE]..**.** 
ccc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ccd0: 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 5d  TL_LOCK_TIMEOUT]
cce0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
ccf0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45  _FCNTL_LOCK_TIME
cd00: 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63 61 75 73  OUT] opcode caus
cd10: 65 73 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6f  es attempts to o
cd20: 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69 6c 65 20  btain.** a file 
cd30: 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68 65 20 78  lock using the x
cd40: 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c 6f 63 6b  Lock or xShmLock
cd50: 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20   methods of the 
cd60: 56 46 53 20 74 6f 20 77 61 69 74 0a 2a 2a 20 66  VFS to wait.** f
cd70: 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69 6c 6c 69  or up to M milli
cd80: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 66  seconds before f
cd90: 61 69 6c 69 6e 67 2c 20 77 68 65 72 65 20 4d 20  ailing, where M 
cda0: 69 73 20 74 68 65 20 73 69 6e 67 6c 65 20 0a 2a  is the single .*
cdb0: 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  * unsigned integ
cdc0: 65 72 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  er parameter..**
cdd0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </ul>.*/.#defin
cde0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
cdf0: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
ce00: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
ce10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45   SQLITE_FCNTL_GE
ce20: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
ce30: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
ce40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54  SQLITE_FCNTL_SET
ce50: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
ce60: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
ce70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
ce80: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
ce90: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
cea0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
ceb0: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  HINT            
cec0: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
ced0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
cee0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
cef0: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
cf00: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
cf10: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
cf20: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
cf30: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
cf40: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20  TTED            
cf50: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
cf60: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
cf70: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39  RETRY          9
cf80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cf90: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
cfa0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  L            10.
cfb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cfc0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20  CNTL_OVERWRITE  
cfd0: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
cfe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
cff0: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20  NTL_VFSNAME     
d000: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64             12.#d
d010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d020: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
d030: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65  RWRITE    13.#de
d040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d050: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  L_PRAGMA        
d060: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66           14.#def
d070: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d080: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20  _BUSYHANDLER    
d090: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69          15.#defi
d0a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d0b0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20  TEMPFILENAME    
d0c0: 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e         16.#defin
d0d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  e SQLITE_FCNTL_M
d0e0: 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20  MAP_SIZE        
d0f0: 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65        18.#define
d100: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52   SQLITE_FCNTL_TR
d110: 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ACE             
d120: 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20       19.#define 
d130: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
d140: 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20  _MOVED          
d150: 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53      20.#define S
d160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
d170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d180: 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51     21.#define SQ
d190: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
d1a0: 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20  T_PHASETWO      
d1b0: 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    22.#define SQL
d1c0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
d1d0: 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20  SET_HANDLE      
d1e0: 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   23.#define SQLI
d1f0: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
d200: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
d210: 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  24.#define SQLIT
d220: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20  E_FCNTL_ZIPVFS  
d230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
d240: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
d250: 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20  _FCNTL_RBU      
d260: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36                26
d270: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d280: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
d290: 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a  R            27.
d2a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d2b0: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
d2c0: 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 23  NTER        28.#
d2d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d2e0: 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41  NTL_WIN32_GET_HA
d2f0: 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64  NDLE       29.#d
d300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d310: 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20 20  TL_PDB          
d320: 20 20 20 20 20 20 20 20 20 20 33 30 0a 23 64 65            30.#de
d330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d340: 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57  L_BEGIN_ATOMIC_W
d350: 52 49 54 45 20 20 20 20 20 33 31 0a 23 64 65 66  RITE     31.#def
d360: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d370: 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57  _COMMIT_ATOMIC_W
d380: 52 49 54 45 20 20 20 20 33 32 0a 23 64 65 66 69  RITE    32.#defi
d390: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d3a0: 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f  ROLLBACK_ATOMIC_
d3b0: 57 52 49 54 45 20 20 33 33 0a 23 64 65 66 69 6e  WRITE  33.#defin
d3c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
d3d0: 4f 43 4b 5f 54 49 4d 45 4f 55 54 20 20 20 20 20  OCK_TIMEOUT     
d3e0: 20 20 20 20 20 20 33 34 0a 0a 2f 2a 20 64 65 70        34../* dep
d3f0: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f  recated names */
d400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d410: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
d420: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
d430: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
d440: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
d450: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
d460: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
d470: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
d480: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
d490: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
d4a0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
d4b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
d4c0: 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a  ST_ERRNO.../*.**
d4d0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
d4e0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
d4f0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
d500: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
d510: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
d520: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
d530: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
d540: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
d550: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
d560: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
d570: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
d580: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
d590: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
d5a0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
d5b0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
d5c0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
d5d0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
d5e0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
d5f0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
d600: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
d610: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
d620: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
d630: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
d640: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
d650: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d660: 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73   Loadable Extens
d670: 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20  ion Thunk.**.** 
d680: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  A pointer to the
d690: 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f   opaque sqlite3_
d6a0: 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72  api_routines str
d6b0: 75 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64  ucture is passed
d6c0: 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64   as.** the third
d6d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e   parameter to en
d6e0: 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c  try points of [l
d6f0: 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f  oadable extensio
d700: 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74  ns].  This.** st
d710: 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20  ructure must be 
d720: 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64  typedefed in ord
d730: 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  er to work aroun
d740: 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69  d compiler warni
d750: 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70  ngs.** on some p
d760: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70  latforms..*/.typ
d770: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d780: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
d790: 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75   sqlite3_api_rou
d7a0: 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tines;../*.** CA
d7b0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
d7c0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
d7d0: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
d7e0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
d7f0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
d800: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
d810: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
d820: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
d830: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
d840: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
d850: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
d860: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
d870: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
d880: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
d890: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
d8a0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
d8b0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
d8c0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
d8d0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
d8e0: 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 69   VFS interface i
d8f0: 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 78 74 65  s sometimes exte
d900: 6e 64 65 64 20 62 79 20 61 64 64 69 6e 67 20 6e  nded by adding n
d910: 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a  ew methods onto.
d920: 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 45 61 63  ** the end.  Eac
d930: 68 20 74 69 6d 65 20 73 75 63 68 20 61 6e 20 65  h time such an e
d940: 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c  xtension occurs,
d950: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
d960: 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d  eld.** is increm
d970: 65 6e 74 65 64 2e 20 20 54 68 65 20 69 56 65 72  ented.  The iVer
d980: 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 61 72 74  sion value start
d990: 65 64 20 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a  ed out as 1 in.*
d9a0: 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f  * SQLite [versio
d9b0: 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74  n 3.5.0] on [dat
d9c0: 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e  eof:3.5.0], then
d9d0: 20 69 6e 63 72 65 61 73 65 64 20 74 6f 20 32 0a   increased to 2.
d9e0: 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 65 20 5b  ** with SQLite [
d9f0: 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f  version 3.7.0] o
da00: 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d  n [dateof:3.7.0]
da10: 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e 63 72 65  , and then incre
da20: 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74  ased.** to 3 wit
da30: 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f  h SQLite [versio
da40: 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74  n 3.7.6] on [dat
da50: 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64  eof:3.7.6].  Add
da60: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
da70: 2a 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  * may be appende
da80: 64 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  d to the sqlite3
da90: 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 6e 64 20  _vfs object and 
daa0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
dab0: 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61  ue.** may increa
dac0: 73 65 20 61 67 61 69 6e 20 69 6e 20 66 75 74 75  se again in futu
dad0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
dae0: 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74  QLite..** Note t
daf0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
db00: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
db10: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
db20: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
db30: 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  ansition from.**
db40: 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e   SQLite [version
db50: 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73   3.5.9] to [vers
db60: 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64  ion 3.6.0] on [d
db70: 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20  ateof:3.6.0].** 
db80: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
db90: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
dba0: 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ot modified..**.
dbb0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
dbc0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
dbd0: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
dbe0: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
dbf0: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
dc00: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
dc10: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
dc20: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
dc30: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
dc40: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
dc50: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
dc60: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
dc70: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
dc80: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
dc90: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
dca0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
dcb0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
dcc0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
dcd0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
dce0: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
dcf0: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
dd00: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
dd10: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
dd20: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
dd30: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
dd40: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
dd50: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
dd60: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
dd70: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
dd80: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
dd90: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
dda0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
ddb0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
ddc0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
ddd0: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
dde0: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
ddf0: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
de00: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
de10: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
de20: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
de30: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
de40: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
de50: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
de60: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
de70: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
de80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
de90: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
dea0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
deb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
dec0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
ded0: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
dee0: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
def0: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
df00: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
df10: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
df20: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
df30: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
df40: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
df50: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
df60: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
df70: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
df80: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
df90: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
dfa0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
dfb0: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
dfc0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
dfd0: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
dfe0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
dff0: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
e000: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
e010: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
e020: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
e030: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
e040: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
e050: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
e060: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
e070: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
e080: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
e090: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
e0a0: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
e0b0: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
e0c0: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
e0d0: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
e0e0: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
e0f0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
e100: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
e110: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
e120: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
e130: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
e140: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
e150: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
e160: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
e170: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
e180: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
e190: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
e1a0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
e1b0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
e1c0: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
e1d0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e1e0: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
e1f0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
e200: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
e210: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
e220: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
e230: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
e240: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
e250: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
e260: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
e270: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
e280: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
e290: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
e2a0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
e2b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
e2c0: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
e2d0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
e2e0: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
e2f0: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
e300: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
e310: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
e320: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
e330: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
e340: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
e350: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
e360: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
e370: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
e380: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
e390: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
e3a0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
e3b0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
e3c0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
e3d0: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
e3e0: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
e3f0: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
e400: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
e410: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
e420: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
e430: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
e440: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
e450: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
e460: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
e470: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
e480: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
e490: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
e4a0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
e4b0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
e4c0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
e4d0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e4e0: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
e4f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e500: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
e510: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e520: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
e530: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e540: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
e550: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
e560: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
e570: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
e580: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
e590: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
e5a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
e5b0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
e5c0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
e5d0: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
e5e0: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
e5f0: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
e600: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
e610: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
e620: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
e630: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
e640: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
e650: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
e660: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
e670: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
e680: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
e690: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
e6a0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
e6b0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
e6c0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
e6d0: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
e6e0: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
e6f0: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
e700: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
e710: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
e720: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
e730: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
e740: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
e750: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
e760: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
e770: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
e780: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
e790: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
e7a0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
e7b0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
e7c0: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
e7d0: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
e7e0: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
e7f0: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
e800: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
e810: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
e820: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
e830: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
e840: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
e850: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
e860: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
e870: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
e880: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
e890: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
e8a0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
e8b0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
e8c0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
e8d0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
e8e0: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
e8f0: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
e900: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
e910: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
e920: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
e930: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
e940: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
e950: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
e960: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
e970: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
e980: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
e990: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
e9a0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
e9b0: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
e9c0: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
e9d0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
e9e0: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
e9f0: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
ea00: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
ea10: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
ea20: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
ea30: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
ea40: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
ea50: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
ea60: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
ea70: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
ea80: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
ea90: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
eaa0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
eab0: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
eac0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
ead0: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
eae0: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
eaf0: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
eb00: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
eb10: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
eb20: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
eb30: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
eb40: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
eb50: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
eb60: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
eb70: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
eb80: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
eb90: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
eba0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
ebb0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
ebc0: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
ebd0: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
ebe0: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
ebf0: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
ec00: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
ec10: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
ec20: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
ec30: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
ec40: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
ec50: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
ec60: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
ec70: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
ec80: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
ec90: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
eca0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
ecb0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
ecc0: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
ecd0: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
ece0: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
ecf0: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
ed00: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
ed10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
ed20: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
ed30: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
ed40: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
ed50: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
ed60: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
ed70: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
ed80: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
ed90: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
eda0: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
edb0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
edc0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
edd0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
ede0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
edf0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
ee00: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
ee10: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
ee20: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
ee30: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
ee40: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
ee50: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
ee60: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
ee70: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
ee80: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
ee90: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
eea0: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
eeb0: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
eec0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
eed0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
eee0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
eef0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
ef00: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
ef10: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
ef20: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
ef30: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
ef40: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
ef50: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
ef60: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
ef70: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
ef80: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
ef90: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
efa0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
efb0: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
efc0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
efd0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
efe0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
eff0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
f000: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
f010: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
f020: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
f030: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
f040: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
f050: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
f060: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
f070: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
f080: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
f090: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
f0a0: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
f0b0: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
f0c0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
f0d0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
f0e0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
f0f0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
f100: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
f110: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
f120: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
f130: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
f140: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
f150: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
f160: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
f170: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
f180: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
f190: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
f1a0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
f1b0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
f1c0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
f1d0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
f1e0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
f1f0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
f200: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
f210: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
f220: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
f230: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
f240: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
f250: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
f260: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
f270: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
f280: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
f290: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
f2a0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
f2b0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
f2c0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
f2d0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
f2e0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
f2f0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
f300: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
f310: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
f320: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
f330: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
f340: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
f350: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
f360: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
f370: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
f380: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
f390: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
f3a0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
f3b0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
f3c0: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
f3d0: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
f3e0: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
f3f0: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
f400: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
f410: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
f420: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
f430: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
f440: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
f450: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
f460: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
f470: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
f480: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
f490: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
f4a0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
f4b0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
f4c0: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
f4d0: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
f4e0: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
f4f0: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
f500: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
f510: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
f520: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
f530: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
f540: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
f550: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
f560: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
f570: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
f580: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
f590: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
f5a0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
f5b0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
f5c0: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
f5d0: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
f5e0: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
f5f0: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
f600: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
f610: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
f620: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
f630: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
f640: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
f650: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
f660: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
f670: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
f680: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
f690: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
f6a0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
f6b0: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
f6c0: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
f6d0: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
f6e0: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
f6f0: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
f700: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
f710: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
f720: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
f730: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
f740: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
f750: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
f760: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
f770: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
f780: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
f790: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
f7a0: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
f7b0: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
f7c0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
f7d0: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
f7e0: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
f7f0: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
f800: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
f810: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
f820: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
f830: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
f840: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
f850: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
f860: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
f870: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
f880: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
f890: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
f8a0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
f8b0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
f8c0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
f8d0: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
f8e0: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
f8f0: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
f900: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
f910: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
f920: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
f930: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
f940: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
f950: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
f960: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
f970: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
f980: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
f990: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
f9a0: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
f9b0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
f9c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
f9d0: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
f9e0: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
f9f0: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
fa00: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
fa10: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
fa20: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fa30: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
fa40: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
fa50: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
fa60: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
fa70: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
fa80: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
fa90: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
faa0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
fab0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
fac0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
fad0: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
fae0: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
faf0: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
fb00: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
fb10: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
fb20: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
fb30: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
fb40: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
fb50: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
fb60: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
fb70: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
fb80: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
fb90: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
fba0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
fbb0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
fbc0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
fbd0: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
fbe0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
fbf0: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
fc00: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
fc10: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
fc20: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
fc30: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
fc40: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
fc50: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
fc60: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
fc70: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
fc80: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
fc90: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
fca0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
fcb0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
fcc0: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
fcd0: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
fce0: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
fcf0: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
fd00: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
fd10: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
fd20: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
fd30: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
fd40: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
fd50: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
fd60: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
fd70: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
fd80: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
fd90: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
fda0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
fdb0: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
fdc0: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
fdd0: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
fde0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
fdf0: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
fe00: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
fe10: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
fe20: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
fe30: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
fe40: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
fe50: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
fe60: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
fe70: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
fe80: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
fe90: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
fea0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
feb0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
fec0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
fed0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
fee0: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
fef0: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
ff00: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
ff10: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
ff20: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
ff30: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
ff40: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
ff50: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
ff60: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
ff70: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
ff80: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
ff90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
ffa0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
ffb0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
ffc0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
ffd0: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
ffe0: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
fff0: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
10000 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
10010 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
10020 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
10030 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
10040 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
10050 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
10060 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
10070 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
10080 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
10090 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
100a0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
100b0 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
100c0 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
100d0 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
100e0 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
100f0 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
10100 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10110 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
10120 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
10130 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
10140 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
10150 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
10160 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
10170 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
10180 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
10190 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
101a0 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
101b0 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
101c0 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
101d0 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
101e0 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
101f0 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
10200 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
10210 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
10220 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
10230 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
10240 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
10250 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
10260 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
10270 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10280 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
10290 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
102a0 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
102b0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
102c0 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
102d0 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
102e0 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
102f0 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
10300 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
10310 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
10320 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
10330 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
10340 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
10350 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10360 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
10370 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
10380 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
10390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
103a0 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
103b0 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
103c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
103d0 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
103e0 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
103f0 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
10400 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
10410 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
10420 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
10430 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
10440 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
10450 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
10460 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
10470 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
10480 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
10490 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
104a0 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
104b0 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
104c0 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
104d0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
104e0 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
104f0 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
10500 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10510 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
10520 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
10530 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10540 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
10550 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
10560 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10570 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
10580 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
10590 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
105a0 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
105b0 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
105c0 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
105d0 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
105e0 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
105f0 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65  ven on the corre
10600 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
10610 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
10620 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
10630 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
10640 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
10650 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
10660 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
10670 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
10680 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
10690 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
106a0 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
106b0 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
106c0 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
106d0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
106e0 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
106f0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
10700 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
10710 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
10720 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
10730 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
10740 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
10750 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
10760 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
10770 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
10780 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
10790 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
107a0 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
107b0 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
107c0 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
107d0 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
107e0 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
107f0 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
10800 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
10810 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
10820 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
10830 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
10840 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10850 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
10860 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
10870 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
10880 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
10890 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
108a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
108b0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
108c0 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
108d0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
108e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
108f0 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
10900 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
10910 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
10920 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
10930 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
10940 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
10950 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
10960 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
10970 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
10980 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
10990 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
109a0 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
109b0 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
109c0 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
109d0 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
109e0 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
109f0 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
10a00 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
10a10 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
10a20 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
10a30 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
10a40 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
10a50 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
10a60 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
10a70 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
10a80 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
10a90 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
10aa0 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
10ab0 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
10ac0 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
10ad0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10ae0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
10af0 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
10b00 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
10b10 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
10b20 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
10b30 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
10b40 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
10b50 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
10b60 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
10b70 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
10b80 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
10b90 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
10ba0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10bb0 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
10bc0 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
10bd0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
10be0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
10bf0 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
10c00 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
10c10 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
10c20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
10c30 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
10c40 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10c50 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
10c60 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
10c70 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
10c80 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
10c90 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
10ca0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
10cb0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
10cc0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10cd0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
10ce0 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
10cf0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10d00 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
10d10 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
10d20 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
10d30 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
10d40 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
10d50 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
10d60 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
10d70 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
10d80 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
10d90 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
10da0 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
10db0 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
10dc0 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
10dd0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
10de0 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
10df0 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
10e00 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
10e10 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
10e20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
10e30 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
10e40 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
10e50 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
10e60 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
10e70 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
10e80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
10e90 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
10ea0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
10eb0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
10ec0 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
10ed0 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
10ee0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10ef0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
10f00 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
10f10 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
10f20 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
10f30 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
10f40 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
10f50 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
10f60 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
10f70 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
10f80 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
10f90 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
10fa0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10fb0 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
10fc0 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
10fd0 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
10fe0 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
10ff0 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
11000 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
11010 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
11020 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
11030 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11040 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
11050 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
11060 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
11070 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
11080 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
11090 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
110a0 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
110b0 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
110c0 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
110d0 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
110e0 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
110f0 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
11100 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
11110 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
11120 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11130 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
11140 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
11150 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
11160 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
11170 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
11180 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
11190 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
111a0 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
111b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
111c0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
111d0 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
111e0 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
111f0 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
11200 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11210 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
11220 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
11230 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
11240 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
11250 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
11260 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11270 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
11280 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
11290 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
112a0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
112b0 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
112c0 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
112d0 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
112e0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
112f0 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
11300 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
11310 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11320 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
11330 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
11340 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
11350 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
11360 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
11370 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
11380 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
11390 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
113a0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
113b0 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
113c0 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
113d0 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
113e0 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
113f0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
11400 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
11410 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
11420 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
11430 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
11440 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
11450 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
11460 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
11470 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
11480 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
11490 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
114a0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
114b0 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
114c0 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
114d0 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
114e0 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
114f0 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
11500 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
11510 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
11520 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
11530 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
11540 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
11550 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
11560 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
11570 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
11580 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
11590 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
115a0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
115b0 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
115c0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
115d0 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
115e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
115f0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
11600 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
11610 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
11620 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
11630 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11640 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
11650 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
11660 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
11670 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
11680 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
11690 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
116a0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
116b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
116c0 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
116d0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
116e0 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
116f0 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
11700 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
11710 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
11720 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
11730 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
11740 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
11750 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
11760 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
11770 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
11780 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
11790 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
117a0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
117b0 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
117c0 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
117d0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
117e0 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
117f0 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
11800 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
11810 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11820 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
11830 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
11840 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
11850 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
11860 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
11870 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
11880 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
11890 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
118a0 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
118b0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
118c0 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
118d0 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
118e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
118f0 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
11900 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
11910 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
11920 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
11930 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
11940 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
11950 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
11960 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
11970 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
11980 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
11990 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
119a0 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
119b0 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
119c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
119d0 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
119e0 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
119f0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
11a00 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
11a10 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
11a20 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
11a30 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
11a40 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
11a50 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
11a60 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
11a70 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
11a80 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65  ds..**.** <b>The
11a90 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11aa0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
11ab0 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54  ot threadsafe. T
11ac0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
11ad0 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68  * must ensure th
11ae0 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
11af0 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
11b00 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
11b10 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
11b20 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
11b30 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
11b40 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  </b>.**.** The s
11b50 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
11b60 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79  interface.** may
11b70 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
11b80 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
11b90 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
11ba0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
11bb0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
11bc0 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
11bd0 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
11be0 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
11bf0 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
11c00 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
11c10 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
11c20 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
11c30 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
11c40 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
11c50 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
11c60 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
11c70 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
11c80 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
11c90 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
11ca0 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
11cb0 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
11cc0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
11cd0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
11ce0 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
11cf0 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
11d00 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
11d10 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
11d20 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
11d30 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
11d40 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
11d50 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
11d60 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
11d70 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
11d80 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
11d90 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
11da0 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
11db0 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
11dc0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11dd0 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
11de0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
11df0 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
11e00 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11e10 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
11e20 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
11e30 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
11e40 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
11e50 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
11e60 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
11e70 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
11e80 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
11e90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
11ea0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
11eb0 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  code]..*/.int sq
11ec0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
11ed0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
11ee0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
11ef0 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
11f00 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  ections.** METHO
11f10 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
11f20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f   The sqlite3_db_
11f30 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
11f40 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
11f50 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ke configuration
11f60 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61  .** changes to a
11f70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11f80 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74  ction].  The int
11f90 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61  erface is simila
11fa0 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
11fb0 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70  _config()] excep
11fc0 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67  t that the chang
11fd0 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69  es apply to a si
11fe0 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ngle.** [databas
11ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73  e connection] (s
12000 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
12010 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e  first argument).
12020 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
12030 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
12040 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
12050 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65  D,V,...)  is the
12060 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  .** [SQLITE_DBCO
12070 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c  NFIG_LOOKASIDE |
12080 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
12090 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65  erb] - an intege
120a0 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20  r code .** that 
120b0 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61  indicates what a
120c0 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
120d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
120e0 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
120f0 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65  igured..** Subse
12100 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20  quent arguments 
12110 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
12120 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
12130 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  ion verb..**.** 
12140 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
12150 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
12160 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
12170 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
12180 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
12190 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
121a0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
121b0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
121c0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
121d0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
121e0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
121f0 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
12200 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
12210 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12220 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
12230 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
12240 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
12250 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
12260 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
12270 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
12280 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
12290 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
122a0 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
122b0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
122c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
122d0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
122e0 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
122f0 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
12300 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
12310 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
12320 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
12330 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
12340 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
12350 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
12360 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
12370 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
12380 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
12390 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
123a0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
123b0 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
123c0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
123d0 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
123e0 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
123f0 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
12400 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
12410 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
12420 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
12430 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
12440 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
12450 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
12460 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
12470 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
12480 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
12490 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
124a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
124b0 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
124c0 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
124d0 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
124e0 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
124f0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
12500 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
12510 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
12520 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
12530 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
12540 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
12550 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
12560 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12570 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
12580 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
12590 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
125a0 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
125b0 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
125c0 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
125d0 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
125e0 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
125f0 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
12600 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
12610 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
12620 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
12630 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
12640 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
12650 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
12660 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
12670 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61  he xMalloc, xRea
12680 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20  lloc, and xFree 
12690 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
126a0 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
126b0 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
126c0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
126d0 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
126e0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
126f0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  ry..** ^SQLite g
12700 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
12710 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
12720 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
12730 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
12740 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
12750 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
12760 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20  xRoundup..**.** 
12770 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
12780 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
12790 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
127a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
127b0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
127c0 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
127d0 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
127e0 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
127f0 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
12800 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
12810 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
12820 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
12830 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
12840 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
12850 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
12860 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
12870 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
12880 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
12890 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
128a0 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
128b0 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
128c0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
128d0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
128e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
128f0 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
12900 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
12910 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
12920 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
12930 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
12940 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
12950 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
12960 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
12970 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
12980 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
12990 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
129a0 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
129b0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
129c0 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
129d0 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
129e0 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
129f0 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
12a00 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
12a10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
12a20 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
12a30 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
12a40 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
12a50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
12a60 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a   For example,.**
12a70 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
12a80 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
12a90 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
12aa0 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
12ab0 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
12ac0 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
12ad0 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
12ae0 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
12af0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
12b00 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
12b10 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
12b20 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
12b30 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
12b40 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
12b50 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
12b60 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
12b70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
12b80 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
12b90 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
12ba0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
12bb0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
12bc0 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
12bd0 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
12be0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
12bf0 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
12c00 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
12c10 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
12c20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
12c30 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
12c40 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
12c50 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
12c60 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
12c70 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
12c80 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
12c90 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
12ca0 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
12cb0 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
12cc0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
12cd0 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
12ce0 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
12cf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12d00 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
12d10 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
12d20 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
12d30 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
12d40 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
12d50 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
12d60 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
12d70 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
12d80 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
12d90 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
12da0 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
12db0 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
12dc0 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
12dd0 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
12de0 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
12df0 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
12e00 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
12e10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
12e20 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
12e30 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
12e40 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
12e50 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
12e60 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
12e70 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
12e80 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
12e90 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
12ea0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12eb0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
12ec0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
12ed0 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
12ee0 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
12ef0 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
12f00 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
12f10 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
12f20 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
12f30 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
12f40 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
12f50 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
12f60 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
12f70 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
12f80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
12f90 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
12fa0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
12fb0 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
12fc0 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
12fd0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
12fe0 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
12ff0 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
13000 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
13010 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
13020 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
13030 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
13040 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
13050 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
13060 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
13070 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
13080 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
13090 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
130a0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
130b0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
130c0 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
130d0 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
130e0 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
130f0 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
13100 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
13110 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
13120 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
13130 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
13140 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
13150 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
13160 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
13170 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
13180 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13190 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
131a0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
131b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
131c0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
131d0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
131e0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
131f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13200 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
13210 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
13220 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
13230 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
13240 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13250 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
13260 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
13270 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
13280 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
13290 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
132a0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
132b0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
132c0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
132d0 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
132e0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
132f0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
13300 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
13310 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
13320 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
13330 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
13340 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
13350 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
13360 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
13370 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13380 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
13390 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
133a0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
133b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
133c0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
133d0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
133e0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
133f0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
13400 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
13410 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
13420 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
13430 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
13440 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
13450 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
13460 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
13470 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
13480 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
13490 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
134a0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
134b0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
134c0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
134d0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
134e0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
134f0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
13500 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
13510 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
13520 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
13530 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
13540 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
13550 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
13560 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
13570 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
13580 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
13590 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
135a0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
135b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
135c0 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
135d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
135e0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
135f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13600 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
13610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13620 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
13630 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
13640 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
13650 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
13660 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
13670 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
13680 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
13690 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
136a0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
136b0 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
136c0 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
136d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
136e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
136f0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
13700 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
13710 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
13720 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
13730 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
13740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13750 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
13760 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
13770 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
13780 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
13790 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
137a0 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
137b0 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
137c0 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
137d0 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
137e0 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
137f0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
13800 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
13810 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13820 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
13830 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
13840 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
13850 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
13860 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
13870 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
13880 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
13890 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
138a0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
138b0 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
138c0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
138d0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
138e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
138f0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
13900 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
13910 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
13920 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
13930 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
13940 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13950 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
13960 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13970 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
13980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
13990 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
139a0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
139b0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
139c0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
139d0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
139e0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
139f0 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
13a00 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
13a10 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
13a20 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
13a30 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
13a40 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
13a50 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
13a60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13a70 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
13a80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
13a90 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
13aa0 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
13ab0 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
13ac0 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
13ad0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
13ae0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13af0 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
13b00 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
13b10 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
13b20 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
13b30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
13b40 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
13b50 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
13b60 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
13b70 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
13b80 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
13b90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13ba0 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
13bb0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
13bc0 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
13bd0 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
13be0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
13bf0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
13c00 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
13c10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
13c20 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
13c30 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
13c40 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13c50 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
13c60 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
13c70 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
13c80 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
13c90 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
13ca0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13cb0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
13cc0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
13cd0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
13ce0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
13cf0 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
13d00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
13d10 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13d20 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
13d30 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13d40 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
13d50 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
13d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
13d70 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
13d80 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13d90 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
13da0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
13db0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
13dc0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
13dd0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
13de0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
13df0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
13e00 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
13e10 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
13e20 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
13e30 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
13e40 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
13e50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
13e60 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
13e70 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
13e80 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
13e90 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
13ea0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
13eb0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
13ec0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
13ed0 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
13ee0 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
13ef0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
13f00 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
13f10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
13f20 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
13f30 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13f40 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
13f50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
13f60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13f70 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
13f80 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13f90 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
13fa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
13fb0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13fc0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
13fd0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
13fe0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
13ff0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
14000 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
14010 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
14020 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
14030 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14040 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
14050 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
14060 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
14070 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
14080 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
14090 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
140a0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
140b0 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
140c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
140d0 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
140e0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
140f0 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
14100 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
14110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d  SQLITE_CONFIG_SM
14120 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  ALL_MALLOC]] <dt
14130 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
14140 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  MALL_MALLOC</dt>
14150 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
14160 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c  LITE_CONFIG_SMAL
14170 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  L_MALLOC option 
14180 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
14190 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65  ument of.** type
141a0 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65   int, interprete
141b0 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20  d as a boolean, 
141c0 77 68 69 63 68 20 69 66 20 74 72 75 65 20 70 72  which if true pr
141d0 6f 76 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f  ovides a hint to
141e0 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20  .** SQLite that 
141f0 69 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20  it should avoid 
14200 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  large memory all
14210 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73  ocations if poss
14220 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ible..** SQLite 
14230 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20  will run faster 
14240 69 66 20 69 74 20 69 73 20 66 72 65 65 20 74 6f  if it is free to
14250 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f   make large memo
14260 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a  ry allocations,.
14270 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c  ** but some appl
14280 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72  ication might pr
14290 65 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77  efer to run slow
142a0 65 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66  er in exchange f
142b0 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  or.** guarantees
142c0 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72   about memory fr
142d0 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  agmentation that
142e0 20 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66   are possible if
142f0 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61   large.** alloca
14300 74 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65  tions are avoide
14310 64 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  d.  This hint is
14320 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a   normally off..*
14330 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
14340 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14350 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
14360 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
14370 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
14380 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
14390 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
143a0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
143b0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
143c0 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74  type int,.** int
143d0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
143e0 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
143f0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
14400 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
14410 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  of.** memory all
14420 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
14430 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
14440 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
14450 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64  tistics are.** d
14460 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
14470 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
14480 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
14490 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
144a0 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
144b0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
144c0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
144d0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
144e0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
144f0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
14500 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
14510 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
14520 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
14530 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20  tatus64()].**   
14540 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
14550 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
14560 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
14570 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
14580 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
14590 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
145a0 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
145b0 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
145c0 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
145d0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
145e0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
145f0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
14600 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
14610 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14620 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c  NFIG_SCRATCH]] <
14630 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14640 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
14650 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
14660 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
14670 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e  option is no lon
14680 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64  ger used..** </d
14690 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
146a0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
146b0 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
146c0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
146d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
146e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
146f0 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f  _PAGECACHE optio
14700 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65  n specifies a me
14710 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61  mory pool.** tha
14720 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
14730 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
14740 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
14750 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
14760 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
14770 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
14780 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
14790 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20  ion option is a 
147a0 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c  no-op if an appl
147b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
147c0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
147d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
147e0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
147f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
14800 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65  CACHE2]..** ^The
14810 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
14820 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
14830 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14840 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
14850 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
14860 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c  d memory (pMem),
14870 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
14880 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e  h page cache lin
14890 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  e (sz),.** and t
148a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63  he number of cac
148b0 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a  he lines (N)..**
148c0 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
148d0 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
148e0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
148f0 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
14900 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
14910 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
14920 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20  and 65536) plus 
14930 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73  some extra bytes
14940 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
14950 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
14960 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20  number of extra 
14970 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20  bytes needed by 
14980 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a  the page header.
14990 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
149a0 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49  ined using [SQLI
149b0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
149c0 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20  _HDRSZ]..** ^It 
149d0 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
149e0 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
149f0 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f  ed memory,.** fo
14a00 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74  r the sz paramet
14a10 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20  er to be larger 
14a20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20  than necessary. 
14a30 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67   The pMem.** arg
14a40 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69  ument must be ei
14a50 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
14a60 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ter or a pointer
14a70 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
14a80 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f   aligned block o
14a90 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c  f memory of at l
14aa0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c  east sz*N bytes,
14ab0 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75   otherwise.** su
14ac0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
14ad0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
14ae0 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73  ** ^When pMem is
14af0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
14b00 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f  e will strive to
14b10 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
14b20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73  provided.** to s
14b30 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68  atisfy page cach
14b40 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67  e needs, falling
14b50 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65   back to [sqlite
14b60 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a  3_malloc()] if.*
14b70 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c  * a page cache l
14b80 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68  ine is larger th
14b90 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69  an sz bytes or i
14ba0 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65  f all of the pMe
14bb0 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65  m buffer.** is e
14bc0 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66  xhausted..** ^If
14bd0 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e   pMem is NULL an
14be0 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  d N is non-zero,
14bf0 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62   then each datab
14c00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
14c10 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61  * does an initia
14c20 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f  l bulk allocatio
14c30 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  n for page cache
14c40 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20   memory.** from 
14c50 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
14c60 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f  )] sufficient fo
14c70 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20  r N cache lines 
14c80 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  if N is positive
14c90 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a   or.** of -1024*
14ca0 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20  N bytes if N is 
14cb0 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20  negative, . ^If 
14cc0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
14cd0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
14ce0 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
14cf0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
14d00 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c  d by the initial
14d10 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  .** allocation, 
14d20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73  then SQLite goes
14d30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
14d40 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c  loc()] separatel
14d50 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64  y for each.** ad
14d60 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c  ditional cache l
14d70 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ine. </dd>.**.**
14d80 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14d90 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
14da0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
14db0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
14dc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14dd0 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  EAP option speci
14de0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
14df0 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20  mory buffer .** 
14e00 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
14e10 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
14e20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
14e30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14e40 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68  eds.** beyond th
14e50 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72  ose provided for
14e60 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
14e70 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
14e80 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  * ^The SQLITE_CO
14e90 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
14ea0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
14eb0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  le if SQLite is 
14ec0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
14ed0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
14ee0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
14ef0 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  or [SQLITE_ENABL
14f00 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72  E_MEMSYS5] and r
14f10 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
14f20 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f  E_ERROR] if invo
14f30 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ked otherwise..*
14f40 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
14f50 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
14f60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14f70 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65  AP:.** An 8-byte
14f80 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
14f90 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
14fa0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
14fb0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
14fc0 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
14fd0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
14fe0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
14ff0 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
15000 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
15010 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
15020 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
15030 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
15040 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
15050 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
15060 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
15070 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
15080 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
15090 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
150a0 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
150b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
150c0 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
150d0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
150e0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74   not NULL then t
150f0 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
15100 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
15110 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
15120 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
15130 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
15140 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
15150 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
15160 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
15170 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
15180 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
15190 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
151a0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
151b0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
151c0 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
151d0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69  fined..** The mi
151e0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
151f0 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20   size is capped 
15200 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e  at 2**12. Reason
15210 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66  able values.** f
15220 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  or the minimum a
15230 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61  llocation size a
15240 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20  re 2**5 through 
15250 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  2**8.</dd>.**.**
15260 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15270 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  _MUTEX]] <dt>SQL
15280 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
15290 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
152a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
152b0 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  G_MUTEX option t
152c0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
152d0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
152e0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
152f0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
15300 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
15310 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
15320 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
15330 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20  ument specifies 
15340 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
15350 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74  level mutex rout
15360 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a  ines to be used.
15370 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20  ** in place the 
15380 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62  mutex routines b
15390 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
153a0 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
153b0 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  es a copy of.** 
153c0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
153d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
153e0 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
153f0 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20  ture before the 
15400 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
15410 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65  te3_config()] re
15420 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74  turns. ^If SQLit
15430 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
15440 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
15450 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
15460 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
15470 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
15480 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
15490 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
154a0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
154b0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
154c0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
154d0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
154e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
154f0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
15500 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f  _CONFIG_MUTEX co
15510 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15520 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
15530 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
15540 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
15550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15560 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
15570 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
15580 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
15590 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
155a0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74  FIG_GETMUTEX opt
155b0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
155c0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
155d0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
155e0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
155f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
15600 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
15610 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a  structure.  The.
15620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ** [sqlite3_mute
15630 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  x_methods].** st
15640 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
15650 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
15660 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74  ntly defined mut
15670 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  ex routines.)^.*
15680 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
15690 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
156a0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
156b0 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69  t mutex allocati
156c0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
156d0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73  ith a wrapper us
156e0 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65  ed to track mute
156f0 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66  x usage for perf
15700 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69  ormance.** profi
15710 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c  ling or testing,
15720 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20   for example.   
15730 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
15740 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
15750 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
15760 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
15770 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
15780 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15790 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
157a0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
157b0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
157c0 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
157d0 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
157e0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
157f0 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
15800 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15810 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67  _GETMUTEX config
15820 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
15830 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
15840 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
15850 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15860 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
15870 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  DE]] <dt>SQLITE_
15880 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15890 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
158a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
158b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69  G_LOOKASIDE opti
158c0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
158d0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
158e0 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66  rmine.** the def
158f0 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f  ault size of loo
15900 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e  kaside memory on
15910 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20   each [database 
15920 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
15930 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15940 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
15950 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
15960 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20  ide buffer slot 
15970 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69  and the second i
15980 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
15990 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74  ** slots allocat
159a0 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ed to each datab
159b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29  ase connection.)
159c0 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46  ^  ^(SQLITE_CONF
159d0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20  IG_LOOKASIDE.** 
159e0 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61  sets the <i>defa
159f0 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
15a00 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
15a10 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15a20 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f  KASIDE].** optio
15a30 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  n to [sqlite3_db
15a40 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62  _config()] can b
15a50 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65  e used to change
15a60 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a   the lookaside.*
15a70 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
15a80 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f  on individual co
15a90 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64  nnections.)^ </d
15aa0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15ab0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
15ac0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15ad0 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74  NFIG_PCACHE2</dt
15ae0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
15af0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15b00 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
15b10 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15b20 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
15b30 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
15b40 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
15b50 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
15b60 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
15b70 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
15b80 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61  e interface to a
15b90 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
15ba0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
15bb0 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  n.)^.** ^SQLite 
15bc0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
15bd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  the [sqlite3_pca
15be0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
15bf0 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ject.</dd>.**.**
15c00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15c10 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
15c20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15c30 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
15c40 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
15c50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
15c60 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
15c70 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15c80 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
15c90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
15ca0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
15cb0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
15cc0 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
15cd0 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72  es of.** the cur
15ce0 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20  rent page cache 
15cf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
15d00 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
15d10 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
15d20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
15d30 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
15d40 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
15d50 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
15d60 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
15d70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
15d80 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
15d90 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
15da0 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
15db0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15dc0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
15dd0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
15de0 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
15df0 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
15e00 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
15e10 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
15e20 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
15e30 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
15e40 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
15e50 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
15e60 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
15e70 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
15e80 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
15e90 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
15ea0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
15eb0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
15ec0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
15ed0 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
15ee0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
15ef0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
15f00 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
15f10 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
15f20 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
15f30 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15f40 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
15f50 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
15f60 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
15f70 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15f80 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
15f90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
15fa0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
15fb0 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
15fc0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
15fd0 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
15fe0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
15ff0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
16000 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
16010 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
16020 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
16030 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
16040 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
16050 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
16060 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
16070 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
16080 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
16090 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
160a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
160b0 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
160c0 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
160d0 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
160e0 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
160f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
16100 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
16110 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
16120 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
16130 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
16140 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
16150 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
16160 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
16170 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
16180 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
16190 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
161a0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
161b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
161c0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
161d0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
161e0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
161f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16200 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
16210 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16220 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
16230 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16240 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b  G_URI option tak
16250 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
16260 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
16270 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  ..** If non-zero
16280 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
16290 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
162a0 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20  enabled. If the 
162b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72  parameter is zer
162c0 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68  o,.** then URI h
162d0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
162e0 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20  lly disabled.)^ 
162f0 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  ^If URI handling
16300 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
16310 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
16320 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f  enames passed to
16330 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
16340 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
16350 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
16360 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
16370 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
16380 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
16390 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
163a0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
163b0 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
163c0 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
163d0 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
163e0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
163f0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
16400 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
16410 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
16420 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61   ^If it is globa
16430 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
16440 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
16450 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
16460 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
16470 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
16480 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
16490 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
164a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
164b0 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75  ened. ^(By defau
164c0 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
164d0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
164e0 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
164f0 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
16500 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
16510 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
16520 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
16530 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
16540 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ned.)^.**.** [[S
16550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
16560 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
16570 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16580 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
16590 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
165a0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
165b0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
165c0 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61  X_SCAN option ta
165d0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74  kes a single int
165e0 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  eger.** argument
165f0 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70   which is interp
16600 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
16610 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  an in order to e
16620 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
16630 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63  .** the use of c
16640 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
16650 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
16660 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72  cans in the quer
16670 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20  y optimizer..** 
16680 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
16690 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e  ting is determin
166a0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51  ed.** by the [SQ
166b0 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52  LITE_ALLOW_COVER
166c0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20  ING_INDEX_SCAN] 
166d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
166e0 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a  ion, or is "on".
166f0 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69  ** if that compi
16700 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
16710 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68  s omitted..** Th
16720 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73  e ability to dis
16730 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20  able the use of 
16740 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
16750 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
16760 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61  scans.** is beca
16770 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65  use some incorre
16780 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63  ctly coded legac
16790 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  y applications m
167a0 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e  ight malfunction
167b0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74  .** when the opt
167c0 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61  imization is ena
167d0 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67  bled.  Providing
167e0 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a   the ability to.
167f0 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f  ** disable the o
16800 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f  ptimization allo
16810 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75  ws the older, bu
16820 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ggy application 
16830 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  code to work.** 
16840 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65  without change e
16850 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76  ven with newer v
16860 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
16870 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
16880 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
16890 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ] [[SQLITE_CONFI
168a0 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a  G_GETPCACHE]].**
168b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
168c0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51  IG_PCACHE and SQ
168d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
168e0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68  CACHE.** <dd> Th
168f0 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20  ese options are 
16900 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f  obsolete and sho
16910 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
16920 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20  by new code..** 
16930 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65  They are retaine
16940 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
16950 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75  compatibility bu
16960 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73  t are now no-ops
16970 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
16980 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16990 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74  _SQLLOG]].** <dt
169a0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
169b0 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69  QLLOG.** <dd>Thi
169c0 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
169d0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71   available if sq
169e0 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  lite is compiled
169f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
16a00 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c  LITE_ENABLE_SQLL
16a10 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f  OG] pre-processo
16a20 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e  r macro defined.
16a30 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
16a40 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  ent should.** be
16a50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
16a60 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65  function of type
16a70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
16a80 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68  qlite3*,const ch
16a90 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68  ar*, int)..** Th
16aa0 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20  e second should 
16ab0 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  be of type (void
16ac0 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  *). The callback
16ad0 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74   is invoked by t
16ae0 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e  he library.** in
16af0 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20   three separate 
16b00 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69  circumstances, i
16b10 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
16b20 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
16b30 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70   the.** fourth p
16b40 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65  arameter. If the
16b50 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
16b60 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65  r is 0, then the
16b70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
16b80 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61  tion.** passed a
16b90 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
16ba0 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62  ument has just b
16bb0 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20  een opened. The 
16bc0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
16bd0 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75  * points to a bu
16be0 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ffer containing 
16bf0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
16c00 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69  main database fi
16c10 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f  le. If the.** fo
16c20 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
16c30 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51  s 1, then the SQ
16c40 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
16c50 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
16c60 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  eter.** points t
16c70 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  o has just been 
16c80 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66  executed. Or, if
16c90 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
16ca0 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e  meter is 2, then
16cb0 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  .** the connecti
16cc0 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20  on being passed 
16cd0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
16ce0 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67  rameter is being
16cf0 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20   closed. The.** 
16d00 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
16d10 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49  is passed NULL I
16d20 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e  n this case.  An
16d30 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e   example of usin
16d40 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67  g this.** config
16d50 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63  uration option c
16d60 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68  an be seen in th
16d70 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63  e "test_sqllog.c
16d80 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e  " source file in
16d90 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61  .** the canonica
16da0 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20  l SQLite source 
16db0 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tree.</dd>.**.**
16dc0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16dd0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
16de0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16df0 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c  G_MMAP_SIZE.** <
16e00 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  dd>^SQLITE_CONFI
16e10 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65  G_MMAP_SIZE take
16e20 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74  s two 64-bit int
16e30 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e  eger (sqlite3_in
16e40 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74  t64) values.** t
16e50 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61  hat are the defa
16e60 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69  ult mmap size li
16e70 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74  mit (the default
16e80 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20   setting for.** 
16e90 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
16ea0 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69  e]) and the maxi
16eb0 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70  mum allowed mmap
16ec0 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20   size limit..** 
16ed0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74  ^The default set
16ee0 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72  ting can be over
16ef0 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64  ridden by each d
16f00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16f10 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68  on using.** eith
16f20 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d  er the [PRAGMA m
16f30 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e  map_size] comman
16f40 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74  d, or by using t
16f50 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
16f60 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
16f70 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28  ile control.  ^(
16f80 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f  The maximum allo
16f90 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a  wed mmap size.**
16fa0 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c   will be silentl
16fb0 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e  y truncated if n
16fc0 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74  ecessary so that
16fd0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63   it does not exc
16fe0 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69  eed the.** compi
16ff0 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
17000 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
17010 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
17020 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
17030 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
17040 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
17050 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
17060 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
17070 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
17080 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
17090 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
170a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
170b0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
170c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
170d0 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
170e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
170f0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
17100 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  E.** <dd>^The SQ
17110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
17120 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f  2_HEAPSIZE optio
17130 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
17140 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
17150 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72  .** compiled for
17160 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68   Windows with th
17170 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  e [SQLITE_WIN32_
17180 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63  MALLOC] pre-proc
17190 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64  essor macro.** d
171a0 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f  efined. ^SQLITE_
171b0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
171c0 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32  PSIZE takes a 32
171d0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
171e0 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74  teger value.** t
171f0 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68  hat specifies th
17200 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
17210 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65  f the created he
17220 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ap..**.** [[SQLI
17230 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
17240 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _HDRSZ]].** <dt>
17250 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
17260 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64  ACHE_HDRSZ.** <d
17270 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
17280 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
17290 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
172a0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
172b0 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  r which.** is a 
172c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
172d0 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73  teger and writes
172e0 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67   into that integ
172f0 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  er the number of
17300 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20   extra.** bytes 
17310 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65  per page require
17320 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20  d for each page 
17330 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  in [SQLITE_CONFI
17340 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
17350 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65   The amount of e
17360 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69  xtra space requi
17370 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64  red can change d
17380 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
17390 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72  compiler,.** tar
173a0 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e  get platform, an
173b0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
173c0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
173d0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a  _CONFIG_PMASZ]].
173e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
173f0 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64  NFIG_PMASZ.** <d
17400 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
17410 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f  NFIG_PMASZ optio
17420 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
17430 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
17440 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e  .** is an unsign
17450 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73  ed integer and s
17460 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d  ets the "Minimum
17470 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74   PMA Size" for t
17480 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  he multithreaded
17490 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68  .** sorter to th
174a0 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65  at integer.  The
174b0 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d   default minimum
174c0 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74   PMA Size is set
174d0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
174e0 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d  TE_SORTER_PMASZ]
174f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17500 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61  tion.  New threa
17510 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a  ds are launched.
17520 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20  ** to help with 
17530 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20  sort operations 
17540 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64  when multithread
17550 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73  ed sorting.** is
17560 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20   enabled (using 
17570 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65  the [PRAGMA thre
17580 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e  ads] command) an
17590 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  d the amount of 
175a0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65  content.** to be
175b0 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20   sorted exceeds 
175c0 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69  the page size ti
175d0 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  mes the minimum 
175e0 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d  of the.** [PRAGM
175f0 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65  A cache_size] se
17600 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76  tting and this v
17610 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  alue..**.** [[SQ
17620 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
17630 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20  JRNL_SPILL]].** 
17640 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17650 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
17660 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
17670 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
17680 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e  RNL_SPILL option
17690 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
176a0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
176b0 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b  ** becomes the [
176c0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
176d0 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b  l] spill-to-disk
176e0 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a   threshold.  .**
176f0 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [Statement jour
17700 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69  nals] are held i
17710 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74  n memory until t
17720 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79  heir size (in by
17730 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20  tes).** exceeds 
17740 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20  this threshold, 
17750 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74  at which point t
17760 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20  hey are written 
17770 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69  to disk..** Or i
17780 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20  f the threshold 
17790 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74  is -1, statement
177a0 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c   journals are al
177b0 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63  ways held.** exc
177c0 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f  lusively in memo
177d0 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e  ry..** Since man
177e0 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  y statement jour
177f0 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d  nals never becom
17800 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67  e large, setting
17810 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68   the spill.** th
17820 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c  reshold to a val
17830 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42  ue such as 64KiB
17840 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64   can greatly red
17850 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  uce the amount o
17860 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65  f.** I/O require
17870 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61  d to support sta
17880 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e  tement rollback.
17890 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
178a0 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73  value for this s
178b0 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f  etting is contro
178c0 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  lled by the.** [
178d0 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f  SQLITE_STMTJRNL_
178e0 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74  SPILL] compile-t
178f0 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c  ime option..** <
17900 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
17910 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
17920 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
17930 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
17940 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
17950 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
17960 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
17970 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17980 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
17990 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
179a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
179b0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
179c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
179d0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
179e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
179f0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
17a00 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
17a10 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
17a20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17a30 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
17a40 20 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67     6  /* No long
17a50 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
17a60 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17a70 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
17a80 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
17a90 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
17aa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17ab0 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
17ac0 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
17ad0 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
17ae0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17af0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
17b00 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
17b10 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
17b20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
17b30 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
17b40 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
17b50 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
17b60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17b70 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
17b80 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
17b90 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
17ba0 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
17bb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
17bc0 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
17bd0 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
17be0 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
17bf0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
17c00 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
17c10 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
17c20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
17c30 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
17c40 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
17c50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17c60 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
17c70 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
17c80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17c90 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
17ca0 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
17cb0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
17cc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
17cd0 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
17ce0 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
17cf0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17d00 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
17d10 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
17d20 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
17d30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17d40 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
17d50 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
17d60 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
17d70 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
17d80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
17d90 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
17da0 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
17db0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17dc0 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
17dd0 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
17de0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
17df0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17e00 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20  MMAP_SIZE    22 
17e10 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36   /* sqlite3_int6
17e20 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  4, sqlite3_int64
17e30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17e40 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
17e50 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33  HEAPSIZE      23
17e60 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a    /* int nByte *
17e70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17e80 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
17e90 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20  DRSZ        24  
17ea0 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23  /* int *psz */.#
17eb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17ec0 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20  NFIG_PMASZ      
17ed0 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20           25  /* 
17ee0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50  unsigned int szP
17ef0 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ma */.#define SQ
17f00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
17f10 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20  JRNL_SPILL      
17f20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65  26  /* int nByte
17f30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17f40 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f  TE_CONFIG_SMALL_
17f50 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37  MALLOC        27
17f60 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
17f70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17f80 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
17f90 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
17fa0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
17fb0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
17fc0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
17fd0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
17fe0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
17ff0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
18000 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
18010 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
18020 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
18030 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
18040 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
18050 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
18060 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
18070 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
18080 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
18090 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
180a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
180b0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
180c0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
180d0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
180e0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
180f0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
18100 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
18110 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
18120 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
18130 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
18140 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
18150 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
18160 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
18170 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
18180 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
18190 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
181a0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
181b0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
181c0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
181d0 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
181e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
181f0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
18200 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
18210 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
18220 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
18230 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
18240 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
18250 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
18260 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
18270 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
18280 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18290 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
182a0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
182b0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
182c0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
182d0 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
182e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
182f0 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
18300 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
18310 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
18320 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
18330 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
18340 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
18350 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
18360 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
18370 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
18380 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
18390 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
183a0 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
183b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
183c0 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
183d0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
183e0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
183f0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
18400 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
18410 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
18420 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
18430 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
18440 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
18450 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
18460 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
18470 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
18480 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
18490 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
184a0 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
184b0 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
184c0 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
184d0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
184e0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
184f0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
18500 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
18510 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
18520 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
18530 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
18540 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
18550 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
18560 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
18570 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
18580 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
18590 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
185a0 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
185b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
185c0 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
185d0 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
185e0 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
185f0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
18600 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
18610 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
18620 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
18630 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
18640 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
18650 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
18660 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
18670 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
18680 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
18690 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
186a0 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
186b0 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
186c0 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
186d0 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
186e0 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
186f0 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
18700 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
18710 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
18720 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
18730 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
18740 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
18750 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
18760 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
18770 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
18780 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
18790 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
187a0 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
187b0 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
187c0 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
187d0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
187e0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
187f0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
18800 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
18810 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
18820 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
18830 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
18840 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
18850 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
18860 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
18870 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
18880 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
18890 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
188a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
188b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
188c0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
188d0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
188e0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
188f0 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
18900 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
18910 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
18920 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
18930 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18940 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
18950 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
18960 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
18970 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
18980 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
18990 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
189a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
189b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
189c0 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
189d0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
189e0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
189f0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
18a00 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
18a10 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
18a20 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
18a30 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
18a40 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
18a50 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
18a60 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
18a70 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
18a80 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
18a90 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
18aa0 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72  o enable trigger
18ab0 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
18ac0 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
18ad0 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
18ae0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18af0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
18b00 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
18b10 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
18b20 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
18b30 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
18b40 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
18b50 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
18b60 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
18b70 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
18b80 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18b90 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
18ba0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
18bb0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
18bc0 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
18bd0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
18be0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
18bf0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18c00 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53  ONFIG_ENABLE_FTS
18c10 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e  3_TOKENIZER</dt>
18c20 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
18c30 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
18c40 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
18c50 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d  le the two-argum
18c60 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f  ent.** version o
18c70 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65  f the [fts3_toke
18c80 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f  nizer()] functio
18c90 6e 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20  n which is part 
18ca0 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d  of the.** [FTS3]
18cb0 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63   full-text searc
18cc0 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69  h engine extensi
18cd0 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  on..** There sho
18ce0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
18cf0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
18d00 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
18d10 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
18d20 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
18d30 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f  to disable fts3_
18d40 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a  tokenizer() or.*
18d50 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
18d60 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69  able fts3_tokeni
18d70 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76  zer() or negativ
18d80 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
18d90 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e  etting.** unchan
18da0 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
18db0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
18dc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
18dd0 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
18de0 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
18df0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
18e00 61 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33  ate whether fts3
18e10 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69  _tokenizer is di
18e20 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
18e30 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
18e40 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
18e50 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18e60 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
18e70 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
18e80 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20  ch case the new 
18e90 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
18ea0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
18eb0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18ec0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18ed0 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53  ABLE_LOAD_EXTENS
18ee0 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ION</dt>.** <dd>
18ef0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
18f00 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
18f10 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b  or disable the [
18f20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
18f30 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74  ension()].** int
18f40 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65  erface independe
18f50 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61  ntly of the [loa
18f60 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53  d_extension()] S
18f70 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  QL function..** 
18f80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  The [sqlite3_ena
18f90 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
18fa0 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65  on()] API enable
18fb0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f  s or disables bo
18fc0 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20  th the.** C-API 
18fd0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
18fe0 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74  tension()] and t
18ff0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
19000 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  [load_extension(
19010 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  )]..** There sho
19020 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
19030 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
19040 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72  .** When the fir
19050 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
19060 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
19070 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68   1, then only th
19080 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e  e C-API is.** en
19090 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51  abled and the SQ
190a0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69  L function remai
190b0 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66  ns disabled.  If
190c0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
190d0 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69  ent to.** this i
190e0 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74  nterface is 0, t
190f0 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41  hen both the C-A
19100 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  PI and the SQL f
19110 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61  unction are disa
19120 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  bled..** If the 
19130 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
19140 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68  s -1, then no ch
19150 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74  anges are made t
19160 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65  o state of eithe
19170 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f  r the.** C-API o
19180 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  r the SQL functi
19190 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  on..** The secon
191a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
191b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
191c0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
191d0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
191e0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
191f0 74 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69  te whether [sqli
19200 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
19210 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  on()] interface.
19220 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f  ** is disabled o
19230 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77  r enabled follow
19240 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
19250 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19260 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61  eter may.** be a
19270 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
19280 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
19290 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
192a0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
192b0 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  k..** </dd>.**.*
192c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
192d0 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45  ONFIG_MAINDBNAME
192e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
192f0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
19300 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
19310 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61   name of the "ma
19320 69 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  in" database.** 
19330 73 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f  schema.  ^The so
19340 6c 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  le argument is a
19350 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f   pointer to a co
19360 6e 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69  nstant UTF8 stri
19370 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  ng.** which will
19380 20 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20   become the new 
19390 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70  schema name in p
193a0 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20  lace of "main". 
193b0 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73   ^SQLite.** does
193c0 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79   not make a copy
193d0 20 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e   of the new main
193e0 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72   schema name str
193f0 69 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c  ing, so the appl
19400 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
19410 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
19420 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
19430 69 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46  into this DBCONF
19440 49 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63  IG option is unc
19450 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20  hanged.** until 
19460 61 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61  after the databa
19470 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c  se connection cl
19480 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  oses..** </dd>.*
19490 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
194a0 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54  DBCONFIG_NO_CKPT
194b0 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a  _ON_CLOSE</dt>.*
194c0 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20  * <dd> Usually, 
194d0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
194e0 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63  in wal mode is c
194f0 6c 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65  losed or detache
19500 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74  d from a .** dat
19510 61 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51  abase handle, SQ
19520 4c 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74  Lite checks if t
19530 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68  his will mean th
19540 61 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77  at there are now
19550 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69   no .** connecti
19560 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68  ons at all to th
19570 65 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73  e database. If s
19580 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61  o, it performs a
19590 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20   checkpoint .** 
195a0 6f 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65  operation before
195b0 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e   closing the con
195c0 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70  nection. This op
195d0 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64  tion may be used
195e0 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20   to.** override 
195f0 74 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20  this behaviour. 
19600 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
19610 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
19620 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  is operation.** 
19630 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20  is an integer - 
19640 70 6f 73 69 74 69 76 65 20 74 6f 20 64 69 73 61  positive to disa
19650 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d  ble checkpoints-
19660 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72  on-close, or zer
19670 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  o (the.** defaul
19680 74 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65  t) to enable the
19690 6d 2c 20 61 6e 64 20 6e 65 67 61 74 69 76 65 20  m, and negative 
196a0 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
196b0 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
196c0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
196d0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
196e0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
196f0 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68  er.** into which
19700 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
19710 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
19720 68 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e  hether checkpoin
19730 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68  ts-on-close.** h
19740 61 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65  ave been disable
19750 64 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72  d - 0 if they ar
19760 65 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20  e not disabled, 
19770 31 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a  1 if they are..*
19780 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
19790 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
197a0 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64  G_ENABLE_QPSG</d
197b0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20  t>.** <dd>^(The 
197c0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
197d0 45 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69  ENABLE_QPSG opti
197e0 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20  on activates or 
197f0 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74  deactivates.** t
19800 68 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65  he [query planne
19810 72 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72  r stability guar
19820 61 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20  antee] (QPSG).  
19830 57 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73  When the QPSG is
19840 20 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69   active,.** a si
19850 6e 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73  ngle SQL query s
19860 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c  tatement will al
19870 77 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d  ways use the sam
19880 65 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61  e algorithm rega
19890 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c  rdless.** of val
198a0 75 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61  ues of [bound pa
198b0 72 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65  rameters].)^ The
198c0 20 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73   QPSG disables s
198d0 6f 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  ome query optimi
198e0 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  zations.** that 
198f0 6c 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75  look at the valu
19900 65 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61  es of bound para
19910 6d 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61  meters, which ca
19920 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72  n make some quer
19930 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20  ies.** slower.  
19940 42 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73  But the QPSG has
19950 20 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f   the advantage o
19960 66 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62  f more predictab
19970 6c 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69  le behavior.  Wi
19980 74 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61  th.** the QPSG a
19990 63 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69  ctive, SQLite wi
199a0 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68  ll always use th
199b0 65 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61  e same query pla
199c0 6e 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61  n in the field a
199d0 73 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75  s.** was used du
199e0 72 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20  ring testing in 
199f0 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 54 68 65 20  the lab..** The 
19a00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
19a10 6f 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69  o this setting i
19a20 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
19a30 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
19a40 6c 65 20 0a 2a 2a 20 74 68 65 20 51 50 53 47 2c  le .** the QPSG,
19a50 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
19a60 62 6c 65 20 51 50 53 47 2c 20 6f 72 20 6e 65 67  ble QPSG, or neg
19a70 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
19a80 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e  he setting.** un
19a90 63 68 61 6e 67 65 64 2e 20 54 68 65 20 73 65 63  changed. The sec
19aa0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
19ab0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
19ac0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
19ad0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
19ae0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
19af0 63 61 74 65 20 77 68 65 74 68 65 72 20 74 68 65  cate whether the
19b00 20 51 50 53 47 20 69 73 20 64 69 73 61 62 6c 65   QPSG is disable
19b10 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
19b20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
19b30 61 6c 6c 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  all..** </dd>.**
19b40 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
19b50 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f  BCONFIG_TRIGGER_
19b60 45 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EQP</dt>.** <dd>
19b70 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
19b80 20 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c 41   output of EXPLA
19b90 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 6f  IN QUERY PLAN co
19ba0 6d 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 20  mmands does not 
19bb0 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 70  .** include outp
19bc0 75 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 61  ut for any opera
19bd0 74 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 20  tions performed 
19be0 62 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  by trigger progr
19bf0 61 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74  ams. This.** opt
19c00 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 73  ion is used to s
19c10 65 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 65  et or clear (the
19c20 20 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 67   default) a flag
19c30 20 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 68   that governs th
19c40 69 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e 20  is.** behavior. 
19c50 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
19c60 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
19c70 69 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  is operation is 
19c80 61 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a 20  an integer -.** 
19c90 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
19ca0 6c 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 72  le output for tr
19cb0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c 20  igger programs, 
19cc0 6f 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 62  or zero to disab
19cd0 6c 65 20 69 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67  le it,.** or neg
19ce0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74  ative to leave t
19cf0 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61  he setting uncha
19d00 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
19d10 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
19d20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
19d30 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
19d40 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 0a  ich is written .
19d50 2a 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  ** 0 or 1 to ind
19d60 69 63 61 74 65 20 77 68 65 74 68 65 72 20 6f 75  icate whether ou
19d70 74 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 65 72  tput-for-trigger
19d80 73 20 68 61 73 20 62 65 65 6e 20 64 69 73 61 62  s has been disab
19d90 6c 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a 20 69  led - 0 if .** i
19da0 74 20 69 73 20 6e 6f 74 20 64 69 73 61 62 6c 65  t is not disable
19db0 64 2c 20 31 20 69 66 20 69 74 20 69 73 2e 20 20  d, 1 if it is.  
19dc0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64  .** </dd>.** </d
19dd0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
19de0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41  LITE_DBCONFIG_MA
19df0 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20  INDBNAME        
19e00 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73      1000 /* cons
19e10 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69  t char* */.#defi
19e20 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
19e30 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
19e40 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a           1001 /*
19e50 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
19e60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19e70 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19e80 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20  _FKEY           
19e90 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1002 /* int int*
19ea0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19eb0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19ec0 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  LE_TRIGGER      
19ed0 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e    1003 /* int in
19ee0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
19ef0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
19f00 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49  ABLE_FTS3_TOKENI
19f10 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20  ZER 1004 /* int 
19f20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
19f30 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19f40 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45  ENABLE_LOAD_EXTE
19f50 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e  NSION 1005 /* in
19f60 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
19f70 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
19f80 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f  G_NO_CKPT_ON_CLO
19f90 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20  SE      1006 /* 
19fa0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
19fb0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
19fc0 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 20  FIG_ENABLE_QPSG 
19fd0 20 20 20 20 20 20 20 20 20 20 31 30 30 37 20 2f            1007 /
19fe0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
19ff0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1a000 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51  ONFIG_TRIGGER_EQ
1a010 50 20 20 20 20 20 20 20 20 20 20 20 31 30 30 38  P           1008
1a020 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1a030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1a040 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20 20 20  BCONFIG_MAX     
1a050 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30                10
1a060 30 38 20 2f 2a 20 4c 61 72 67 65 73 74 20 44 42  08 /* Largest DB
1a070 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  CONFIG */../*.**
1a080 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
1a090 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
1a0a0 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
1a0b0 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1a0c0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1a0d0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1a0e0 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
1a0f0 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
1a100 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
1a110 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1a120 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
1a130 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
1a140 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
1a150 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
1a160 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1a170 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
1a180 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
1a190 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y..*/.int sqlite
1a1a0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
1a1b0 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
1a1c0 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
1a1d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
1a1e0 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
1a1f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1a200 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  te3.**.** ^Each 
1a210 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51  entry in most SQ
1a220 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 63  Lite tables (exc
1a230 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54  ept for [WITHOUT
1a240 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a   ROWID] tables).
1a250 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  ** has a unique 
1a260 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
1a270 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
1a280 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
1a290 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
1a2a0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
1a2b0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
1a2c0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
1a2d0 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
1a2e0 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
1a2f0 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
1a300 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
1a310 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
1a320 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
1a330 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
1a340 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
1a350 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
1a360 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
1a370 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
1a380 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
1a390 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
1a3a0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
1a3b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1a3c0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1a3d0 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 20  id(D) interface 
1a3e0 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  usually returns 
1a3f0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a  the [rowid] of.*
1a400 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  * the most recen
1a410 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  t successful [IN
1a420 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77  SERT] into a row
1a430 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72  id table or [vir
1a440 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f  tual table].** o
1a450 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
1a460 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74  ction D. ^Insert
1a470 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20  s into [WITHOUT 
1a480 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72  ROWID] tables ar
1a490 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65  e not.** recorde
1a4a0 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73  d. ^If no succes
1a4b0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69  sful [INSERT]s i
1a4c0 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73  nto rowid tables
1a4d0 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
1a4e0 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64  red .** on the d
1a4f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a500 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c 69 74  on D, then sqlit
1a510 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1a520 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20  owid(D) returns 
1a530 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  .** zero..**.** 
1a540 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 6e 67  As well as being
1a550 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 61 6c   set automatical
1a560 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 20 69  ly as rows are i
1a570 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 61 74  nserted into dat
1a580 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c  abase.** tables,
1a590 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a5a0 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
1a5b0 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 74 20  tion may be set 
1a5c0 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a  explicitly by.**
1a5d0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61   [sqlite3_set_la
1a5e0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1a5f0 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69  )].**.** Some vi
1a600 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
1a610 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
1a620 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e 74 6f  INSERT rows into
1a630 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 61 73   rowid tables as
1a640 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d  .** part of comm
1a650 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 61 63  itting a transac
1a660 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c  tion (e.g. to fl
1a670 75 73 68 20 64 61 74 61 20 61 63 63 75 6d 75 6c  ush data accumul
1a680 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a  ated in memory.*
1a690 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74  * to disk). In t
1a6a0 68 69 73 20 63 61 73 65 20 73 75 62 73 65 71 75  his case subsequ
1a6b0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 68 69  ent calls to thi
1a6c0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1a6d0 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61  n the rowid.** a
1a6e0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
1a6f0 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e  hese internal IN
1a700 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c  SERT operations,
1a710 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 6f 20   which leads to 
1a720 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 65 20  .** unintuitive 
1a730 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 61 6c  results. Virtual
1a740 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
1a750 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f 20 77  ations that do w
1a760 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a  rite to rowid.**
1a770 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 73 20   tables in this 
1a780 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 74 68  way can avoid th
1a790 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 72 65  is problem by re
1a7a0 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 69 67  storing the orig
1a7b0 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76  inal .** rowid v
1a7c0 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  alue using [sqli
1a7d0 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73  te3_set_last_ins
1a7e0 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 65 66  ert_rowid()] bef
1a7f0 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a  ore returning .*
1a800 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65  * control to the
1a810 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   user..**.** ^(I
1a820 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
1a830 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
1a840 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 73 20  igger then this 
1a850 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a  routine will .**
1a860 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77   return the [row
1a870 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
1a880 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  ted row as long 
1a890 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69  as the trigger i
1a8a0 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f  s .** running. O
1a8b0 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
1a8c0 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 74 68  program ends, th
1a8d0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a8e0 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
1a8f0 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
1a900 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
1a910 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 77  re the trigger w
1a920 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a  as fired.)^.**.*
1a930 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
1a940 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
1a950 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
1a960 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
1a970 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
1a980 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
1a990 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
1a9a0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1a9b0 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
1a9c0 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
1a9d0 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
1a9e0 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
1a9f0 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
1aa00 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
1aa10 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
1aa20 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
1aa30 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
1aa40 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
1aa50 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
1aa60 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
1aa70 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
1aa80 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
1aa90 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
1aaa0 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
1aab0 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
1aac0 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
1aad0 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
1aae0 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
1aaf0 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
1ab00 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
1ab10 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
1ab20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
1ab30 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
1ab40 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
1ab50 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
1ab60 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
1ab70 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
1ab80 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
1ab90 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
1aba0 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
1abb0 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
1abc0 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
1abd0 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
1abe0 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
1abf0 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
1ac00 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
1ac10 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
1ac20 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
1ac30 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1ac40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1ac50 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1ac60 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
1ac70 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
1ac80 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
1ac90 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1aca0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
1acb0 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
1acc0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
1acd0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
1ace0 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
1acf0 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
1ad00 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
1ad10 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
1ad20 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1ad30 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
1ad40 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
1ad50 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1ad60 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
1ad70 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
1ad80 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
1ad90 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
1ada0 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  id]..*/.sqlite3_
1adb0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61  int64 sqlite3_la
1adc0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1add0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
1ade0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
1adf0 74 68 65 20 4c 61 73 74 20 49 6e 73 65 72 74 20  the Last Insert 
1ae00 52 6f 77 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20  Rowid value..** 
1ae10 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1ae20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1ae30 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
1ae40 74 5f 72 6f 77 69 64 28 44 2c 20 52 29 20 6d 65  t_rowid(D, R) me
1ae50 74 68 6f 64 20 61 6c 6c 6f 77 73 20 74 68 65 20  thod allows the 
1ae60 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a  application to.*
1ae70 2a 20 73 65 74 20 74 68 65 20 76 61 6c 75 65 20  * set the value 
1ae80 72 65 74 75 72 6e 65 64 20 62 79 20 63 61 6c 6c  returned by call
1ae90 69 6e 67 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  ing sqlite3_last
1aea0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
1aeb0 20 74 6f 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75   to R .** withou
1aec0 74 20 69 6e 73 65 72 74 69 6e 67 20 61 20 72 6f  t inserting a ro
1aed0 77 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  w into the datab
1aee0 61 73 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ase..*/.void sql
1aef0 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1af00 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
1af10 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  e3*,sqlite3_int6
1af20 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  4);../*.** CAPI3
1af30 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
1af40 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
1af50 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
1af60 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1af70 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
1af80 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
1af90 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
1afa0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a  ed, inserted or.
1afb0 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  ** deleted by th
1afc0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
1afd0 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
1afe0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1aff0 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
1b000 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
1b010 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69  connection speci
1b020 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79  fied by the only
1b030 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1b040 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
1b050 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
1b060 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
1b070 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61  ot modify the va
1b080 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1b090 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
1b0a0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68  ..**.** ^Only ch
1b0b0 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63  anges made direc
1b0c0 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52  tly by the INSER
1b0d0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1b0e0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
1b0f0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
1b100 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e  - auxiliary chan
1b110 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43  ges caused by [C
1b120 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
1b130 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b  triggers], .** [
1b140 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
1b150 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45  ons] or [REPLACE
1b160 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
1b170 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20  olution are not 
1b180 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
1b190 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
1b1a0 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
1b1b0 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49  cepted by .** [I
1b1c0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1b1d0 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74  r | INSTEAD OF t
1b1e0 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74  riggers] are not
1b1f0 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76   counted. ^The v
1b200 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65  alue .** returne
1b210 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1b220 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65  nges() immediate
1b230 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45  ly after an INSE
1b240 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a  RT, UPDATE or .*
1b250 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
1b260 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77  nt run on a view
1b270 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
1b280 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61   Only changes ma
1b290 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74  de to real .** t
1b2a0 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65  ables are counte
1b2b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20  d..**.** Things 
1b2c0 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  are more complic
1b2d0 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69  ated if the sqli
1b2e0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
1b2f0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65  nction is.** exe
1b300 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72  cuted while a tr
1b310 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73  igger program is
1b320 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d   running. This m
1b330 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ay happen if the
1b340 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
1b350 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
1b360 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f  SQL function], o
1b370 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20  r if some other 
1b380 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
1b390 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c  tion invokes sql
1b3a0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64  ite3_changes() d
1b3b0 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69  irectly. Essenti
1b3c0 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  ally:.** .** <ul
1b3d0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65  >.**   <li> ^(Be
1b3e0 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20  fore entering a 
1b3f0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1b400 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1b410 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
1b420 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1b430 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61  ) function is sa
1b440 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74  ved. After the t
1b450 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a  rigger program .
1b460 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69  **        has fi
1b470 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67  nished, the orig
1b480 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65  inal value is re
1b490 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a  stored.)^.** .**
1b4a0 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e     <li> ^(Within
1b4b0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1b4c0 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20  am each INSERT, 
1b4d0 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54  UPDATE and DELET
1b4e0 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61  E .**        sta
1b4f0 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20  tement sets the 
1b500 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1b510 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
1b520 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75  s() .**        u
1b530 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61  pon completion a
1b540 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75  s normal. Of cou
1b550 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20  rse, this value 
1b560 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65  will not include
1b570 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20   .**        any 
1b580 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65  changes performe
1b590 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72  d by sub-trigger
1b5a0 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65  s, as the sqlite
1b5b0 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
1b5c0 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c         value wil
1b5d0 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72  l be saved and r
1b5e0 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61  estored after ea
1b5f0 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68  ch sub-trigger h
1b600 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75  as run.)^.** </u
1b610 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20  l>.** .** ^This 
1b620 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68  means that if th
1b630 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  e changes() SQL 
1b640 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d  function (or sim
1b650 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a  ilar) is used.**
1b660 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e   by the first IN
1b670 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1b680 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1b690 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
1b6a0 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e  r, it .** return
1b6b0 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73  s the value as s
1b6c0 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  et when the call
1b6d0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65  ing statement be
1b6e0 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  gan executing..*
1b6f0 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64  * ^If it is used
1b700 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f   by the second o
1b710 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63  r subsequent suc
1b720 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  h statement with
1b730 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a  in a trigger .**
1b740 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61   program, the va
1b750 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66  lue returned ref
1b760 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72  lects the number
1b770 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
1b780 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65  d by the .** pre
1b790 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50  vious INSERT, UP
1b7a0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1b7b0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1b7c0 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
1b7d0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1b7e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
1b7f0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
1b800 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
1b810 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
1b820 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
1b830 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
1b840 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1b850 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1b860 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1b870 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1b880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b890 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1b8a0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
1b8b0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1b8c0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1b8d0 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
1b8e0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
1b8f0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
1b900 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
1b910 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1b920 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b930 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
1b940 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1b950 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1b960 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1b970 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1b980 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
1b990 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20   rows inserted, 
1b9a0 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64  modified or.** d
1b9b0 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49  eleted by all [I
1b9c0 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
1b9d0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
1b9e0 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65  tements complete
1b9f0 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64  d.** since the d
1ba00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ba10 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69  on was opened, i
1ba20 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65  ncluding those e
1ba30 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61  xecuted as.** pa
1ba40 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72  rt of trigger pr
1ba50 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69  ograms. ^Executi
1ba60 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
1ba70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
1ba80 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61  nt.** does not a
1ba90 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20  ffect the value 
1baa0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1bab0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1bac0 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61  s()..** .** ^Cha
1bad0 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72  nges made as par
1bae0 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65  t of [foreign ke
1baf0 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69  y actions] are i
1bb00 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a  ncluded in the.*
1bb10 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f  * count, but tho
1bb20 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  se made as part 
1bb30 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
1bb40 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
1bb50 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68   are.** not. ^Ch
1bb60 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
1bb70 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
1bb80 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20  pted by INSTEAD 
1bb90 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20  OF triggers .** 
1bba0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1bbb0 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  .** .** See also
1bbc0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
1bbd0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1bbe0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
1bbf0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1bc00 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
1bc10 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
1bc20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1bc30 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1bc40 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1bc50 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1bc60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1bc70 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1bc80 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1bc90 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1bca0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1bcb0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
1bcc0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1bcd0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1bce0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1bcf0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
1bd00 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1bd10 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
1bd20 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
1bd30 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
1bd40 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1bd50 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1bd60 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
1bd70 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
1bd80 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
1bd90 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
1bda0 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
1bdb0 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
1bdc0 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
1bdd0 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
1bde0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
1bdf0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
1be00 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
1be10 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
1be20 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
1be30 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
1be40 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
1be50 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
1be60 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
1be70 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
1be80 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
1be90 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
1bea0 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
1beb0 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
1bec0 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
1bed0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
1bee0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
1bef0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
1bf00 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1bf10 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
1bf20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1bf30 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
1bf40 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
1bf50 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
1bf60 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1bf70 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1bf80 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
1bf90 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
1bfa0 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
1bfb0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
1bfc0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1bfd0 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
1bfe0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
1bff0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
1c000 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
1c010 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
1c020 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
1c030 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
1c040 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
1c050 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
1c060 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
1c070 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
1c080 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
1c090 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
1c0a0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1c0b0 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1c0c0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
1c0d0 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
1c0e0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1c0f0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
1c100 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
1c110 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
1c120 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
1c130 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
1c140 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
1c150 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
1c160 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
1c170 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
1c180 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1c190 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
1c1a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c1b0 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
1c1c0 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
1c1d0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1c1e0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1c1f0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1c200 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1c210 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
1c220 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
1c230 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
1c240 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
1c250 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
1c260 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
1c270 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
1c280 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1c290 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
1c2a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1c2b0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1c2c0 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
1c2d0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
1c2e0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
1c2f0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
1c300 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
1c310 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
1c320 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
1c330 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1c340 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
1c350 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
1c360 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
1c370 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
1c380 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
1c390 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
1c3a0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1c3b0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1c3c0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1c3d0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1c3e0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f  l returns..*/.vo
1c3f0 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
1c400 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
1c410 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c420 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
1c430 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
1c440 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
1c450 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1c460 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
1c470 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
1c480 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
1c490 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
1c4a0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
1c4b0 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
1c4c0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1c4d0 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
1c4e0 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
1c4f0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
1c500 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
1c510 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
1c520 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
1c530 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
1c540 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
1c550 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
1c560 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
1c570 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1c580 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
1c590 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
1c5a0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
1c5b0 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
1c5c0 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
1c5d0 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
1c5e0 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
1c5f0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
1c600 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
1c610 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
1c620 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
1c630 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
1c640 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
1c650 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
1c660 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
1c670 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
1c680 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
1c690 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
1c6a0 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
1c6b0 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
1c6c0 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
1c6d0 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
1c6e0 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
1c6f0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
1c700 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
1c710 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
1c720 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
1c730 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
1c740 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
1c750 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1c760 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
1c770 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
1c780 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
1c790 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
1c7a0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
1c7b0 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
1c7c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1c7d0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1c7e0 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
1c7f0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1c800 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
1c810 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
1c820 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
1c830 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
1c840 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
1c850 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
1c860 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
1c870 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
1c880 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
1c890 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
1c8a0 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
1c8b0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
1c8c0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
1c8d0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1c8e0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
1c8f0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
1c900 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
1c910 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
1c920 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
1c930 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
1c940 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
1c950 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
1c960 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1c970 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1c980 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
1c990 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
1c9a0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1c9b0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1c9c0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1c9d0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1c9e0 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
1c9f0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1ca00 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1ca10 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
1ca20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1ca30 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
1ca40 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
1ca50 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
1ca60 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1ca70 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
1ca80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
1ca90 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
1caa0 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
1cab0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
1cac0 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
1cad0 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
1cae0 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
1caf0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79   KEYWORDS: {busy
1cb00 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
1cb10 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72  k} {busy handler
1cb20 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
1cb30 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
1cb40 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1cb50 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74  dler(D,X,P) rout
1cb60 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
1cb70 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a  ack function X.*
1cb80 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  * that might be 
1cb90 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
1cba0 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
1cbb0 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
1cbc0 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
1cbd0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1cbe0 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
1cbf0 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
1cc00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65  onnection] D whe
1cc10 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  n another thread
1cc20 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
1cc30 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63  as the table loc
1cc40 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ked..** The sqli
1cc50 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1cc60 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1cc70 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1cc80 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  t.** [sqlite3_bu
1cc90 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e  sy_timeout()] an
1cca0 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  d [PRAGMA busy_t
1ccb0 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  imeout]..**.** ^
1ccc0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1ccd0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
1cce0 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
1ccf0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
1cd00 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
1cd10 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
1cd20 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
1cd30 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
1cd40 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
1cd50 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1cd60 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
1cd70 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
1cd80 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
1cd90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1cda0 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
1cdb0 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
1cdc0 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
1cdd0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
1cde0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
1cdf0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
1ce00 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
1ce10 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1ce20 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
1ce30 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
1ce40 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
1ce50 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
1ce60 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1ce70 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
1ce80 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ked previously f
1ce90 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b  or the same lock
1cea0 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
1ceb0 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
1cec0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
1ced0 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
1cee0 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
1cef0 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
1cf00 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1cf10 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
1cf20 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20   is returned.** 
1cf30 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1cf40 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  on..** ^If the c
1cf50 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1cf60 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
1cf70 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
1cf80 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  * is made to acc
1cf90 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1cfa0 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
1cfb0 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
1cfc0 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
1cfd0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
1cfe0 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
1cff0 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
1d000 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
1d010 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
1d020 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
1d030 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
1d040 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
1d050 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
1d060 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
1d070 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
1d080 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
1d090 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
1d0a0 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68  E_BUSY].** to th
1d0b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e  e application in
1d0c0 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
1d0d0 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68  g the .** busy h
1d0e0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
1d0f0 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
1d100 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
1d110 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1d120 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
1d130 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
1d140 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
1d150 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
1d160 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
1d170 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1d180 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
1d190 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
1d1a0 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
1d1b0 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
1d1c0 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
1d1d0 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
1d1e0 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
1d1f0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1d200 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
1d210 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1d220 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
1d230 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
1d240 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1d250 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
1d260 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
1d270 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
1d280 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
1d290 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
1d2a0 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
1d2b0 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
1d2c0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1d2d0 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
1d2e0 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
1d2f0 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
1d300 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
1d310 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
1d320 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
1d330 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
1d340 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
1d350 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
1d360 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
1d370 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
1d380 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
1d390 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1d3a0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1d3b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
1d3c0 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
1d3d0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1d3e0 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
1d3f0 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
1d400 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
1d410 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1d420 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
1d430 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
1d440 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1d450 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20  imeout()].** or 
1d460 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47  evaluating [PRAG
1d470 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d  MA busy_timeout=
1d480 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74  N] will change t
1d490 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  he.** busy handl
1d4a0 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61  er and thus clea
1d4b0 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79  r any previously
1d4c0 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65   set busy handle
1d4d0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
1d4e0 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
1d4f0 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
1d500 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
1d510 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
1d520 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1d530 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1d540 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49  busy handler.  I
1d550 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a  n other words,.*
1d560 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1d570 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  er is not reentr
1d580 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ant.  Any such a
1d590 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
1d5a0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
1d5b0 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
1d5c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
1d5d0 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
1d5e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d5f0 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
1d600 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1d610 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1d620 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1d630 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  /.int sqlite3_bu
1d640 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
1d650 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 2a  e3*,int(*)(void*
1d660 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f  ,int),void*);../
1d670 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1d680 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
1d690 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
1d6a0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1d6b0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1d6c0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1d6d0 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1d6e0 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1d6f0 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1d700 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1d710 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1d720 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1d730 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1d740 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1d750 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1d760 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1d770 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1d780 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1d790 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1d7a0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1d7b0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1d7c0 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1d7d0 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1d7e0 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1d7f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d800 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1d810 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
1d820 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1d830 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1d840 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1d850 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1d860 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1d870 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1d880 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1d890 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1d8a0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1d8b0 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1d8c0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1d8d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
1d8e0 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1d8f0 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1d900 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1d910 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1d920 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1d930 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1d940 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1d950 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1d960 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1d970 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1d980 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
1d990 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
1d9a0 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69  sy_timeout].*/.i
1d9b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1d9c0 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a  timeout(sqlite3*
1d9d0 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a  , int ms);../*.*
1d9e0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76  * CAPI3REF: Conv
1d9f0 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73  enience Routines
1da00 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65   For Running Que
1da10 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ries.** METHOD: 
1da20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
1da30 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69  is is a legacy i
1da40 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73  nterface that is
1da50 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62   preserved for b
1da60 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1da70 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f  bility..** Use o
1da80 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
1da90 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e   is not recommen
1daa0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e  ded..**.** Defin
1dab0 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75  ition: A <b>resu
1dac0 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20  lt table</b> is 
1dad0 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75  memory data stru
1dae0 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79  cture created by
1daf0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1db00 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e  _get_table()] in
1db10 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75  terface.  A resu
1db20 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73  lt table records
1db30 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   the.** complete
1db40 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66   query results f
1db50 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  rom one or more 
1db60 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  queries..**.** T
1db70 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74  he table concept
1db80 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62  ually has a numb
1db90 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63  er of rows and c
1dba0 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20  olumns.  But.** 
1dbb0 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72  these numbers ar
1dbc0 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68  e not part of th
1dbd0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
1dbe0 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a  tself.  These.**
1dbf0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74   numbers are obt
1dc00 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79  ained separately
1dc10 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20  .  Let N be the 
1dc20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a  number of rows.*
1dc30 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e  * and M be the n
1dc40 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1dc50 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1dc60 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72   table is an arr
1dc70 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1dc80 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1dc90 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e  d UTF-8 strings.
1dca0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e  .** There are (N
1dcb0 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69  +1)*M elements i
1dcc0 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68  n the array.  Th
1dcd0 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65  e first M pointe
1dce0 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a  rs point.** to z
1dcf0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1dd00 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e  trings that  con
1dd10 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
1dd20 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  f the columns..*
1dd30 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20  * The remaining 
1dd40 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e  entries all poin
1dd50 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c  t to query resul
1dd60 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73  ts.  NULL values
1dd70 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55   result.** in NU
1dd80 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c  LL pointers.  Al
1dd90 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61  l other values a
1dda0 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d  re in their UTF-
1ddb0 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  8 zero-terminate
1ddc0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72  d.** string repr
1ddd0 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65  esentation as re
1dde0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
1ddf0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
1de00 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  ]..**.** A resul
1de10 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f  t table might co
1de20 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20  nsist of one or 
1de30 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  more memory allo
1de40 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69  cations..** It i
1de50 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61  s not safe to pa
1de60 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ss a result tabl
1de70 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73  e directly to [s
1de80 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
1de90 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1dea0 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c  e should be deal
1deb0 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73  located using [s
1dec0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1ded0 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73  e()]..**.** ^(As
1dee0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
1def0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1df00 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
1df10 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
1df20 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
1df30 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1df40 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1df50 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
1df60 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d   Age.**        -
1df70 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1df80 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
1df90 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
1dfa0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
1dfb0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
1dfc0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
1dfd0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
1dfe0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1dff0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
1e000 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
1e010 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
1e020 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
1e030 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
1e040 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
1e050 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
1e060 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
1e070 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
1e080 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
1e090 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
1e0a0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
1e0b0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
1e0c0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1e0d0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1e0e0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
1e0f0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1e100 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
1e110 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
1e120 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
1e130 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
1e140 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1e150 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
1e160 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1e170 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
1e180 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1e190 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
1e1a0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1e1b0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
1e1c0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
1e1d0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
1e1e0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
1e1f0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1e200 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1e210 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1e220 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61   function evalua
1e230 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  tes one or more.
1e240 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
1e250 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  arated SQL state
1e260 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72  ments in the zer
1e270 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1e280 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20  -8.** string of 
1e290 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65  its 2nd paramete
1e2a0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  r and returns a 
1e2b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20  result table to 
1e2c0 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67  the.** pointer g
1e2d0 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20  iven in its 3rd 
1e2e0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
1e2f0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69   After the appli
1e300 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73  cation has finis
1e310 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73  hed with the res
1e320 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ult from sqlite3
1e330 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a  _get_table(),.**
1e340 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68   it must pass th
1e350 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
1e360 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
1e370 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
1e380 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
1e390 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1e3a0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
1e3b0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
1e3c0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
1e3d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e3e0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
1e3f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1e400 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
1e410 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
1e420 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
1e430 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
1e440 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
1e450 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
1e460 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
1e470 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
1e480 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
1e490 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
1e4a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1e4b0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
1e4c0 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
1e4d0 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
1e4e0 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
1e4f0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
1e500 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
1e510 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
1e520 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
1e530 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
1e540 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
1e550 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
1e560 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
1e570 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
1e580 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
1e590 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
1e5a0 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
1e5b0 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
1e5c0 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
1e5d0 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
1e5e0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
1e5f0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
1e600 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
1e610 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
1e620 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1e630 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
1e640 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
1e650 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f  e3_errmsg()]..*/
1e660 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74  .int sqlite3_get
1e670 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
1e680 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1e690 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
1e6a0 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
1e6b0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
1e6c0 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
1e6d0 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
1e6e0 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
1e6f0 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
1e700 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
1e710 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
1e720 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1e730 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
1e740 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
1e750 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
1e760 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1e770 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
1e780 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1e790 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
1e7a0 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
1e7b0 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
1e7c0 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71  re */.);.void sq
1e7d0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1e7e0 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b  (char **result);
1e7f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e800 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69  : Formatted Stri
1e810 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63  ng Printing Func
1e820 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1e830 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77  e routines are w
1e840 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68  ork-alikes of th
1e850 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d  e "printf()" fam
1e860 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ily of functions
1e870 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61  .** from the sta
1e880 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1e890 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1e8a0 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f  es understand mo
1e8b0 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e  st of the common
1e8c0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1e8d0 6f 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ons from.** the 
1e8e0 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79  standard library
1e8f0 20 70 72 69 6e 74 66 28 29 20 0a 2a 2a 20 70 6c   printf() .** pl
1e900 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  us some addition
1e910 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20  al non-standard 
1e920 66 6f 72 6d 61 74 73 20 28 5b 25 71 5d 2c 20 5b  formats ([%q], [
1e930 25 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e 64 20 5b  %Q], [%w], and [
1e940 25 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20 74 68 65  %z])..** See the
1e950 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74   [built-in print
1e960 66 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  f()] documentati
1e970 6f 6e 20 66 6f 72 20 64 65 74 61 69 6c 73 2e 0a  on for details..
1e980 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e990 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
1e9a0 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
1e9b0 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
1e9c0 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
1e9d0 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
1e9e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
1e9f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1ea00 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
1ea10 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
1ea20 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
1ea30 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
1ea40 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
1ea50 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
1ea60 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
1ea70 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
1ea80 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
1ea90 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d 20 69 73  3_malloc64()] is
1eaa0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
1eab0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
1eac0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
1ead0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
1eae0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  g..**.** ^(The s
1eaf0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1eb00 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
1eb10 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
1eb20 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
1eb30 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1eb40 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
1eb50 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
1eb60 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
1eb70 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
1eb80 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1eb90 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
1eba0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
1ebb0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
1ebc0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
1ebd0 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
1ebe0 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
1ebf0 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
1ec00 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
1ec10 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
1ec20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
1ec30 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
1ec40 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
1ec50 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
1ec60 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1ec70 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
1ec80 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
1ec90 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
1eca0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1ecb0 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
1ecc0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
1ecd0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
1ece0 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
1ecf0 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
1ed00 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
1ed10 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
1ed20 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1ed30 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
1ed40 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
1ed50 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
1ed60 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
1ed70 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
1ed80 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
1ed90 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1eda0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
1edb0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
1edc0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
1edd0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
1ede0 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
1edf0 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
1ee00 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1ee10 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
1ee20 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
1ee30 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
1ee40 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
1ee50 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1ee60 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
1ee70 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
1ee80 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
1ee90 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
1eea0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
1eeb0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
1eec0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
1eed0 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
1eee0 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
1eef0 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
1ef00 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cters..**.** ^Th
1ef10 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69  e sqlite3_vsnpri
1ef20 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1ef30 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69   a varargs versi
1ef40 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1ef50 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20  printf()..**.** 
1ef60 53 65 65 20 61 6c 73 6f 3a 20 20 5b 62 75 69 6c  See also:  [buil
1ef70 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 5d 2c 20  t-in printf()], 
1ef80 5b 70 72 69 6e 74 66 28 29 20 53 51 4c 20 66 75  [printf() SQL fu
1ef90 6e 63 74 69 6f 6e 5d 0a 2a 2f 0a 63 68 61 72 20  nction].*/.char 
1efa0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1efb0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1efc0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1efd0 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1efe0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1eff0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1f000 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1f010 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1f020 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1f030 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1f040 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1f050 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1f060 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1f070 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1f080 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1f090 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1f0a0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1f0b0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1f0c0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1f0d0 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1f0e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1f0f0 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1f100 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1f110 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1f120 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1f130 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1f140 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1f150 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1f160 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1f170 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1f180 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1f190 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1f1a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f1b0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1f1c0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1f1d0 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1f1e0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1f1f0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1f200 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1f210 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1f220 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1f230 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1f240 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1f250 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1f260 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1f270 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1f280 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1f290 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1f2a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1f2b0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1f2c0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1f2d0 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1f2e0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1f2f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1f300 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1f310 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1f320 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1f330 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1f340 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1f350 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1f360 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1f370 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1f380 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1f390 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1f3a0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1f3b0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1f3c0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1f3d0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1f3e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1f3f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1f400 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1f410 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1f420 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1f430 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1f440 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1f450 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1f460 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1f470 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1f480 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1f490 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1f4a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1f4b0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1f4c0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1f4d0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1f4e0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1f4f0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1f500 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1f510 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1f520 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1f530 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1f540 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1f550 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1f560 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1f570 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1f580 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1f590 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1f5a0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1f5b0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1f5c0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1f5d0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1f5e0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1f5f0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1f600 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1f610 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1f620 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1f630 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f640 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1f650 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1f660 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1f670 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1f680 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1f690 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1f6a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1f6b0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1f6c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1f6d0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1f6e0 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1f6f0 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1f700 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1f710 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1f720 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
1f730 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
1f740 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f750 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
1f760 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1f770 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1f780 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1f790 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1f7a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
1f7b0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1f7c0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1f7d0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1f7e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1f7f0 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1f800 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1f810 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
1f820 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1f830 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
1f840 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1f850 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1f860 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1f870 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1f880 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1f890 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1f8a0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1f8b0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1f8c0 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1f8d0 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1f8e0 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
1f8f0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1f900 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1f910 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1f920 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
1f930 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
1f940 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
1f950 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
1f960 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
1f970 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1f980 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
1f990 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
1f9a0 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
1f9b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
1f9c0 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
1f9d0 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
1f9e0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
1f9f0 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1fa00 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
1fa10 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
1fa20 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
1fa30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
1fa40 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
1fa50 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1fa60 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1fa70 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1fa80 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1fa90 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
1faa0 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
1fab0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1fac0 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
1fad0 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
1fae0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
1faf0 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
1fb00 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1fb10 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
1fb20 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
1fb30 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
1fb40 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
1fb50 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
1fb60 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
1fb70 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
1fb80 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
1fb90 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1fba0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
1fbb0 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
1fbc0 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
1fbd0 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
1fbe0 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
1fbf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
1fc00 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
1fc10 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
1fc20 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
1fc30 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
1fc40 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
1fc50 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1fc60 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
1fc70 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
1fc80 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
1fc90 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
1fca0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1fcb0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1fcc0 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
1fcd0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
1fce0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1fcf0 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
1fd00 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
1fd10 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1fd20 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1fd30 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1fd40 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1fd50 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1fd60 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1fd70 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1fd80 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1fd90 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1fda0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1fdb0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1fdc0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1fdd0 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1fde0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1fdf0 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1fe00 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1fe10 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1fe20 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1fe30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1fe40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1fe50 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1fe60 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1fe70 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1fe80 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1fe90 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1fea0 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1feb0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1fec0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1fed0 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1fee0 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1fef0 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1ff00 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1ff10 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1ff20 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1ff30 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1ff40 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1ff50 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1ff60 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1ff70 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1ff80 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1ff90 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1ffa0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1ffb0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1ffc0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1ffd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1ffe0 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1fff0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
20000 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
20010 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
20020 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
20030 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
20040 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
20050 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
20060 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
20070 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
20080 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
20090 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
200a0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
200b0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
200c0 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
200d0 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
200e0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
200f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
20100 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
20110 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
20120 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
20130 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
20140 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
20150 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
20160 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
20170 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
20180 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
20190 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
201a0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
201b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
201c0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
201d0 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
201e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
201f0 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
20200 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
20210 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
20220 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
20230 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
20240 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
20250 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73  alloc64(void*, s
20260 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
20270 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
20280 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65  e(void*);.sqlite
20290 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  3_uint64 sqlite3
202a0 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
202b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
202c0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
202d0 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
202e0 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
202f0 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
20300 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
20310 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
20320 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
20330 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
20340 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
20350 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
20360 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
20370 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
20380 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
20390 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
203a0 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
203b0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
203c0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
203d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
203e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
203f0 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
20400 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
20410 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
20420 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
20430 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
20440 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
20450 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
20460 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
20470 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
20480 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
20490 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
204a0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
204b0 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
204c0 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
204d0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
204e0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
204f0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
20500 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
20510 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
20520 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
20530 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
20540 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
20550 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
20560 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
20570 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
20580 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
20590 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
205a0 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
205b0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
205c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
205d0 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
205e0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
205f0 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
20600 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
20610 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
20620 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
20630 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
20640 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
20650 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
20660 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
20670 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
20680 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
20690 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
206a0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
206b0 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
206c0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
206d0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
206e0 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
206f0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
20700 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
20710 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
20720 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
20730 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
20740 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
20750 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
20760 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
20770 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
20780 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
20790 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
207a0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
207b0 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
207c0 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
207d0 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
207e0 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
207f0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
20800 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
20810 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
20820 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
20830 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
20840 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
20850 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
20860 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
20870 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
20880 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
20890 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
208a0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
208b0 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
208c0 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
208d0 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
208e0 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
208f0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
20900 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
20910 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
20920 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
20930 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
20940 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
20950 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
20960 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
20970 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
20980 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
20990 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
209a0 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
209b0 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
209c0 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
209d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
209e0 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
209f0 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
20a00 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
20a10 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
20a20 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
20a30 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
20a40 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
20a50 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
20a60 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
20a70 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
20a80 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
20a90 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
20aa0 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
20ab0 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
20ac0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
20ad0 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
20ae0 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
20af0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
20b00 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
20b10 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
20b20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
20b30 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
20b40 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
20b50 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
20b60 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
20b70 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
20b80 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
20b90 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20  HOD: sqlite3.** 
20ba0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f  KEYWORDS: {autho
20bb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a  rizer callback}.
20bc0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
20bd0 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e  ine registers an
20be0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20bf0 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
20c00 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
20c10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
20c20 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
20c30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
20c40 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
20c50 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20c60 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
20c70 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
20c80 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
20c90 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
20ca0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
20cb0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
20cc0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
20cd0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
20ce0 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v3()], [sqlit
20cf0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
20d00 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20d10 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e  e16_v2()],.** an
20d20 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
20d30 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74  re16_v3()].  ^At
20d40 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e   various.** poin
20d50 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f  ts during the co
20d60 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73  mpilation proces
20d70 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62  s, as logic is b
20d80 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20  eing created.** 
20d90 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
20da0 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  us actions, the 
20db0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20dc0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  ack is invoked t
20dd0 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73  o.** see if thos
20de0 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c  e actions are al
20df0 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74  lowed.  ^The aut
20e00 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20e10 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
20e20 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
20e30 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
20e40 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
20e50 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
20e60 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
20e70 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
20e80 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
20e90 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
20ea0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
20eb0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
20ec0 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
20ed0 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
20ee0 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
20ef0 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
20f00 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75  ror.  ^If the au
20f10 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20f20 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  k returns.** any
20f30 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61   value other tha
20f40 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  n [SQLITE_IGNORE
20f50 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ], [SQLITE_OK], 
20f60 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
20f70 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71  .** then the [sq
20f80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
20f90 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e  ()] or equivalen
20fa0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  t call that trig
20fb0 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74  gered.** the aut
20fc0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69  horizer will fai
20fd0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  l with an error 
20fe0 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57  message..**.** W
20ff0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
21000 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
21010 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  _OK], that means
21020 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
21030 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f  * requested is o
21040 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61  k.  ^When the ca
21050 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
21060 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68  SQLITE_DENY], th
21070 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
21080 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65  epare_v2()] or e
21090 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74  quivalent call t
210a0 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68  hat triggered th
210b0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
210c0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61  will fail with a
210d0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
210e0 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a  explaining that.
210f0 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e  ** access is den
21100 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ied. .**.** ^The
21110 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
21120 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
21130 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
21140 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
21150 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
21160 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
21170 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
21180 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20  interface. ^The 
21190 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
211a0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
211b0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
211c0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c  r [SQLITE_COPY |
211d0 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68   action code] th
211e0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
211f0 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61  the particular a
21200 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
21210 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69  orized. ^The thi
21220 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68  rd through sixth
21230 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
21240 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  o the callback a
21250 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70  re either NULL p
21260 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d  ointers or zero-
21270 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
21280 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61  gs.** that conta
21290 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65  in additional de
212a0 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20  tails about the 
212b0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
212c0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c  horized..** Appl
212d0 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c  ications must al
212e0 77 61 79 73 20 62 65 20 70 72 65 70 61 72 65 64  ways be prepared
212f0 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20   to encounter a 
21300 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20  NULL pointer in 
21310 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68  any.** of the th
21320 69 72 64 20 74 68 72 6f 75 67 68 20 74 68 65 20  ird through the 
21330 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
21340 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a   of the authoriz
21350 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ation callback..
21360 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
21370 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
21380 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
21390 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
213a0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
213b0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
213c0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
213d0 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
213e0 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
213f0 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
21400 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
21410 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
21420 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
21430 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
21440 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
21450 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
21460 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
21470 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
21480 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
21490 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
214a0 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
214b0 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
214c0 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
214d0 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
214e0 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  When a table is 
214f0 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 61 20  referenced by a 
21500 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20  [SELECT] but no 
21510 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72  column values ar
21520 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66  e.** extracted f
21530 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28  rom that table (
21540 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61  for example in a
21550 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22   query like.** "
21560 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20  SELECT count(*) 
21570 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20  FROM tab") then 
21580 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  the [SQLITE_READ
21590 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  ] authorizer cal
215a0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f  lback.** is invo
215b0 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61  ked once for tha
215c0 74 20 74 61 62 6c 65 20 77 69 74 68 20 61 20 63  t table with a c
215d0 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20  olumn name that 
215e0 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  is an empty stri
215f0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  ng..** ^If the a
21600 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
21610 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
21620 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
21630 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
21640 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
21650 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
21660 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
21670 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
21680 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
21690 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
216a0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
216b0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
216c0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
216d0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
216e0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
216f0 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
21700 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
21710 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
21720 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
21730 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
21740 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
21750 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
21760 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
21770 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
21780 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
21790 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
217a0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
217b0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
217c0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
217d0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
217e0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
217f0 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
21800 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
21810 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
21820 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
21830 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
21840 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
21850 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
21860 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
21870 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
21880 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
21890 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
218a0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
218b0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
218c0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
218d0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
218e0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
218f0 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
21900 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
21910 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
21920 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
21930 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
21940 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
21950 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
21960 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
21970 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
21980 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
21990 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
219a0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
219b0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
219c0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
219d0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
219e0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
219f0 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
21a00 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
21a10 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
21a20 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
21a30 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
21a40 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
21a50 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
21a60 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
21a70 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
21a80 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
21a90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
21aa0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
21ab0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
21ac0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
21ad0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
21ae0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
21af0 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
21b00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
21b10 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
21b20 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
21b30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
21b40 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
21b50 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
21b60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21b70 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
21b80 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
21b90 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
21ba0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21bb0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
21bc0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
21bd0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
21be0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
21bf0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
21c00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
21c10 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
21c20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
21c30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
21c40 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
21c50 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
21c60 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
21c70 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
21c80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
21c90 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
21ca0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
21cb0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
21cc0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
21cd0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
21ce0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
21cf0 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
21d00 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
21d10 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
21d20 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
21d30 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
21d40 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
21d50 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
21d60 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
21d70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
21d80 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
21d90 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
21da0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
21db0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
21dc0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
21dd0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
21de0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
21df0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
21e00 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
21e10 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
21e20 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
21e30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21e40 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
21e50 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
21e60 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
21e70 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
21e80 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
21e90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
21ea0 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
21eb0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
21ec0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
21ed0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
21ee0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
21ef0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
21f00 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
21f10 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
21f20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
21f30 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
21f40 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
21f50 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
21f60 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
21f70 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
21f80 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
21f90 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
21fa0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
21fb0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
21fc0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
21fd0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
21fe0 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
21ff0 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
22000 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
22010 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
22020 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
22030 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
22040 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
22050 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
22060 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
22070 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
22080 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
22090 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
220a0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
220b0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
220c0 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
220d0 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
220e0 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
220f0 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
22100 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
22110 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
22120 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
22130 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
22140 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
22150 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
22160 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
22170 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
22180 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
22190 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
221a0 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
221b0 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
221c0 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
221d0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
221e0 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
221f0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
22200 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
22210 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
22220 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
22230 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
22240 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
22250 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
22260 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
22270 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
22280 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
22290 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
222a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
222b0 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
222c0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
222d0 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
222e0 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
222f0 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
22300 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
22310 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
22320 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22330 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
22340 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
22350 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
22360 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
22370 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
22380 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
22390 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
223a0 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
223b0 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
223c0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
223d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
223e0 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
223f0 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
22400 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
22410 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
22420 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
22430 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
22440 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
22450 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
22460 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22470 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
22480 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
22490 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
224a0 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
224b0 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
224c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
224d0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
224e0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
224f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
22500 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
22510 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
22520 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
22530 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
22540 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
22550 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
22560 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
22570 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
22580 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
22590 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
225a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
225b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
225c0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
225d0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
225e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
225f0 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
22600 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
22610 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
22620 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22640 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
22650 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
22660 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22670 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22690 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
226a0 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
226b0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
226c0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
226d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
226e0 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
226f0 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
22700 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22710 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22720 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22730 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
22740 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
22750 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
22760 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22770 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22780 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
22790 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
227a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
227b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
227c0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
227d0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
227e0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
227f0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
22800 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22810 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
22820 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
22830 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
22840 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22850 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22860 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
22870 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
22880 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22890 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
228a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
228b0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
228c0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
228d0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
228e0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
228f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22900 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
22910 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
22920 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22930 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22940 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22950 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
22960 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
22970 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
22980 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22990 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
229a0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
229b0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
229c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
229d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
229e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
229f0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
22a00 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
22a10 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
22a20 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22a30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22a40 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
22a50 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
22a60 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
22a70 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22a90 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
22aa0 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
22ab0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
22ac0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22ae0 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
22af0 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
22b00 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
22b10 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22b20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
22b30 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
22b40 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
22b50 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
22b60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
22b80 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
22b90 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
22ba0 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
22bb0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
22bc0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
22bd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22be0 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
22bf0 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
22c00 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
22c10 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
22c20 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
22c30 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
22c40 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
22c50 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22c60 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
22c70 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
22c80 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
22c90 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
22ca0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22cb0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
22cc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
22cd0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22ce0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
22cf0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
22d00 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
22d10 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
22d20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
22d30 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22d40 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22d50 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
22d60 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
22d70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
22d80 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
22d90 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22da0 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
22db0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
22dc0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
22dd0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
22de0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22df0 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
22e00 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
22e10 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
22e20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22e30 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22e40 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
22e50 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
22e60 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22e70 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22e80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22e90 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
22ea0 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
22eb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22ec0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
22ed0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22ee0 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
22ef0 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
22f00 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
22f10 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
22f20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22f30 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
22f40 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
22f50 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
22f60 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
22f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22f80 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
22f90 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
22fa0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
22fb0 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
22fc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22fd0 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
22fe0 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
22ff0 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
23000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
23010 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
23020 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
23030 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
23040 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
23050 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
23060 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
23070 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
23080 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
23090 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
230a0 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63  tines are deprec
230b0 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73  ated. Use the [s
230c0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
230d0 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
230e0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72  instead of the r
230f0 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65  outines describe
23100 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  d here..**.** Th
23110 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
23120 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
23130 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
23140 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
23150 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
23160 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
23170 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
23180 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
23190 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
231a0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
231b0 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
231c0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
231d0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
231e0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
231f0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
23200 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
23210 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
23220 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
23230 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
23240 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
23250 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
23260 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
23270 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
23280 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
23290 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
232a0 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
232b0 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
232c0 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
232d0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
232e0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
232f0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
23300 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
23310 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
23320 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
23330 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
23340 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
23350 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
23360 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
23370 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
23380 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
23390 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
233a0 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
233b0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
233c0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
233d0 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
233e0 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
233f0 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
23400 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
23410 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
23420 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
23430 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
23440 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
23450 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
23460 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
23470 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
23480 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
23490 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
234a0 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
234b0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
234c0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
234d0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
234e0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
234f0 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
23500 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
23510 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
23520 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
23530 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
23540 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
23550 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
23560 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
23570 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
23580 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
23590 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
235a0 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
235b0 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
235c0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
235d0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
235e0 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
235f0 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
23600 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
23610 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
23620 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
23630 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
23640 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
23650 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
23660 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
23670 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
23680 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
23690 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50  e..*/.SQLITE_DEP
236a0 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
236b0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
236c0 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
236d0 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
236e0 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
236f0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
23700 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74  ATED void *sqlit
23710 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
23720 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
23730 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
23740 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
23750 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
23760 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23770 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76  EF: SQL Trace Ev
23780 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ent Codes.** KEY
23790 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52  WORDS: SQLITE_TR
237a0 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ACE.**.** These 
237b0 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69  constants identi
237c0 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76  fy classes of ev
237d0 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65  ents that can be
237e0 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73   monitored.** us
237f0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
23800 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61  _trace_v2()] tra
23810 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65  cing logic.  The
23820 20 4d 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74   M argument.** t
23830 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
23840 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 5d 20 69 73  _v2(D,M,X,P)] is
23850 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e   an OR-ed combin
23860 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20  ation of one or 
23870 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66  more of.** the f
23880 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e  ollowing constan
23890 74 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ts.  ^The first 
238a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
238b0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  trace callback.*
238c0 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  * is one of the 
238d0 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61  following consta
238e0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74  nts..**.** New t
238f0 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  racing constants
23900 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
23910 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
23920 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65  ..**.** ^A trace
23930 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f   callback has fo
23940 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43  ur arguments: xC
23950 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29  allback(T,C,P,X)
23960 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75  ..** ^The T argu
23970 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74  ment is one of t
23980 68 65 20 69 6e 74 65 67 65 72 20 74 79 70 65 20  he integer type 
23990 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20  codes above..** 
239a0 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20  ^The C argument 
239b0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
239c0 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
239d0 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68   passed in as th
239e0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75  e.** fourth argu
239f0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
23a00 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a  _trace_v2()]..**
23a10 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67   The P and X arg
23a20 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74  uments are point
23a30 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e  ers whose meanin
23a40 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a  gs depend on T..
23a50 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
23a60 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
23a70 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  T]] <dt>SQLITE_T
23a80 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a  RACE_STMT</dt>.*
23a90 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
23aa0 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c  _TRACE_STMT call
23ab0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
23ac0 77 68 65 6e 20 61 20 70 72 65 70 61 72 65 64 20  when a prepared 
23ad0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72  statement.** fir
23ae0 73 74 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e  st begins runnin
23af0 67 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61  g and possibly a
23b00 74 20 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75  t other times du
23b10 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63  ring the.** exec
23b20 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65  ution of the pre
23b30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c  pared statement,
23b40 20 73 75 63 68 20 61 73 20 61 74 20 74 68 65 20   such as at the 
23b50 73 74 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a  start of each.**
23b60 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67   trigger subprog
23b70 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75  ram. ^The P argu
23b80 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
23b90 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65  r to the.** [pre
23ba0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23bb0 2e 20 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e  . ^The X argumen
23bc0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
23bd0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
23be0 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70  .** is the unexp
23bf0 61 6e 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f  anded SQL text o
23c00 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  f the prepared s
23c10 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53  tatement or an S
23c20 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74  QL comment .** t
23c30 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68  hat indicates th
23c40 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  e invocation of 
23c50 61 20 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65  a trigger.  ^The
23c60 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f   callback can co
23c70 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d  mpute.** the sam
23c80 65 20 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c  e text that woul
23c90 64 20 68 61 76 65 20 62 65 65 6e 20 72 65 74 75  d have been retu
23ca0 72 6e 65 64 20 62 79 20 74 68 65 20 6c 65 67 61  rned by the lega
23cb0 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  cy [sqlite3_trac
23cc0 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  e()].** interfac
23cd0 65 20 62 79 20 75 73 69 6e 67 20 74 68 65 20 58  e by using the X
23ce0 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58   argument when X
23cf0 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d   begins with "--
23d00 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a  " and invoking.*
23d10 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  * [sqlite3_expan
23d20 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65  ded_sql(P)] othe
23d30 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rwise..**.** [[S
23d40 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
23d50 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ILE]] <dt>SQLITE
23d60 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f  _TRACE_PROFILE</
23d70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
23d80 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
23d90 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f  ILE callback pro
23da0 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74  vides approximat
23db0 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  ely the same.** 
23dc0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69  information as i
23dd0 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
23de0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  e [sqlite3_profi
23df0 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a  le()] callback..
23e00 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
23e10 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
23e20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
23e30 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
23e40 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e  the.** X argumen
23e50 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34  t points to a 64
23e60 2d 62 69 74 20 69 6e 74 65 67 65 72 20 77 68 69  -bit integer whi
23e70 63 68 20 69 73 20 74 68 65 20 65 73 74 69 6d 61  ch is the estima
23e80 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75  ted of.** the nu
23e90 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  mber of nanoseco
23ea0 6e 64 20 74 68 61 74 20 74 68 65 20 70 72 65 70  nd that the prep
23eb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74  ared statement t
23ec0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e  ook to run..** ^
23ed0 54 68 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  The SQLITE_TRACE
23ee0 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63  _PROFILE callbac
23ef0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
23f00 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
23f10 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20  finishes..**.** 
23f20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  [[SQLITE_TRACE_R
23f30 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OW]] <dt>SQLITE_
23f40 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a  TRACE_ROW</dt>.*
23f50 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
23f60 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62  _TRACE_ROW callb
23f70 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23f80 68 65 6e 65 76 65 72 20 61 20 70 72 65 70 61 72  henever a prepar
23f90 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
23fa0 67 65 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67  generates a sing
23fb0 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74  le row of result
23fc0 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72  .  .** ^The P ar
23fd0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
23fe0 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70  ter to the [prep
23ff0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
24000 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67  and the.** X arg
24010 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e  ument is unused.
24020 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
24030 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64  TRACE_CLOSE]] <d
24040 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  t>SQLITE_TRACE_C
24050 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LOSE</dt>.** <dd
24060 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
24070 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b  E_CLOSE callback
24080 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
24090 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
240a0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
240b0 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75  ..** ^The P argu
240c0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
240d0 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  r to the [databa
240e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
240f0 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65  bject.** and the
24100 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75   X argument is u
24110 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  nused..** </dl>.
24120 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24130 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20  E_TRACE_STMT    
24140 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20     0x01.#define 
24150 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
24160 46 49 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65  FILE    0x02.#de
24170 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
24180 45 5f 52 4f 57 20 20 20 20 20 20 20 20 30 78 30  E_ROW        0x0
24190 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
241a0 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20  _TRACE_CLOSE    
241b0 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41    0x08../*.** CA
241c0 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63  PI3REF: SQL Trac
241d0 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44  e Hook.** METHOD
241e0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
241f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
24200 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69  ce_v2(D,M,X,P) i
24210 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
24220 72 73 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62  rs a trace callb
24230 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
24240 58 20 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62  X against [datab
24250 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
24260 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74  D, using propert
24270 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20  y mask M.** and 
24280 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20  context pointer 
24290 50 2e 20 20 5e 49 66 20 74 68 65 20 58 20 63 61  P.  ^If the X ca
242a0 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c  llback is.** NUL
242b0 4c 20 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61  L or if the M ma
242c0 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  sk is zero, then
242d0 20 74 72 61 63 69 6e 67 20 69 73 20 64 69 73 61   tracing is disa
242e0 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20  bled.  The.** M 
242f0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
24300 62 65 20 74 68 65 20 62 69 74 77 69 73 65 20 4f  be the bitwise O
24310 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  R-ed combination
24320 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d   of.** zero or m
24330 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  ore [SQLITE_TRAC
24340 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a  E] constants..**
24350 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74  .** ^Each call t
24360 6f 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33  o either sqlite3
24370 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69  _trace() or sqli
24380 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f  te3_trace_v2() o
24390 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61  verrides .** (ca
243a0 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72  ncels) any prior
243b0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
243c0 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c  3_trace() or sql
243d0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e  ite3_trace_v2().
243e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61  .**.** ^The X ca
243f0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
24400 64 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f  d whenever any o
24410 66 20 74 68 65 20 65 76 65 6e 74 73 20 69 64 65  f the events ide
24420 6e 74 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d  ntified by .** m
24430 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54  ask M occur.  ^T
24440 68 65 20 69 6e 74 65 67 65 72 20 72 65 74 75 72  he integer retur
24450 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65  n value from the
24460 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72   callback is cur
24470 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65  rently.** ignore
24480 64 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d  d, though this m
24490 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74  ay change in fut
244a0 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43  ure releases.  C
244b0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65  allback.** imple
244c0 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
244d0 64 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f  d return zero to
244e0 20 65 6e 73 75 72 65 20 66 75 74 75 72 65 20 63   ensure future c
244f0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
24500 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c  .** ^A trace cal
24510 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
24520 20 77 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d   with four argum
24530 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54  ents: callback(T
24540 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65  ,C,P,X)..** ^The
24550 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f   T argument is o
24560 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ne of the [SQLIT
24570 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73  E_TRACE].** cons
24580 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74  tants to indicat
24590 65 20 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61  e why the callba
245a0 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a  ck was invoked..
245b0 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65  ** ^The C argume
245c0 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  nt is a copy of 
245d0 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  the context poin
245e0 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e  ter..** The P an
245f0 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72  d X arguments ar
24600 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65  e pointers whose
24610 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64   meanings depend
24620 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   on T..**.** The
24630 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
24640 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
24650 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70   intended to rep
24660 6c 61 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a  lace the legacy.
24670 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
24680 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20  qlite3_trace()] 
24690 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f  and [sqlite3_pro
246a0 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66  file()], both of
246b0 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65   which.** are de
246c0 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74  precated..*/.int
246d0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
246e0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  2(.  sqlite3*,. 
246f0 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c   unsigned uMask,
24700 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63  .  int(*xCallbac
24710 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64  k)(unsigned,void
24720 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a  *,void*,void*),.
24730 20 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a    void *pCtx.);.
24740 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24750 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
24760 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
24770 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
24780 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
24790 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
247a0 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
247b0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
247c0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
247d0 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
247e0 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
247f0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
24800 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
24810 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
24820 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
24830 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
24840 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
24850 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
24860 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
24870 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
24880 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
24890 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
248a0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
248b0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
248c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
248d0 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
248e0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
248f0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
24900 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
24910 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
24920 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
24930 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
24940 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
24950 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
24960 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
24970 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
24980 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
24990 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
249a0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
249b0 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
249c0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
249d0 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
249e0 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
249f0 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
24a00 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
24a10 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
24a20 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
24a30 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
24a40 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
24a50 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
24a60 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
24a70 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
24a80 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
24a90 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
24aa0 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
24ab0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
24ac0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
24ad0 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
24ae0 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
24af0 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
24b00 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
24b10 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
24b20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
24b30 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
24b40 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
24b50 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
24b60 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
24b70 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
24b80 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
24b90 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
24ba0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
24bb0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
24bc0 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
24bd0 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
24be0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
24bf0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
24c00 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
24c10 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
24c20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24c30 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
24c40 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
24c50 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
24c60 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
24c70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
24c80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
24c90 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
24ca0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
24cb0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
24cc0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
24cd0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
24ce0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
24cf0 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
24d00 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
24d10 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
24d20 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
24d30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24d40 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
24d50 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
24d60 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  tion.** CONSTRUC
24d70 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  TOR: sqlite3.**.
24d80 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
24d90 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
24da0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
24db0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
24dc0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
24dd0 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
24de0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
24df0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
24e00 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
24e10 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
24e20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
24e30 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
24e40 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
24e50 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
24e60 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
24e70 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
24e80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
24e90 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
24ea0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
24eb0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
24ec0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
24ed0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
24ee0 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
24ef0 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
24f00 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
24f10 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
24f20 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
24f30 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
24f40 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
24f50 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
24f60 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
24f70 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
24f80 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
24f90 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
24fa0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
24fb0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
24fc0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
24fd0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
24fe0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
24ff0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
25000 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
25010 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
25020 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
25030 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
25040 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
25050 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
25060 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
25070 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
25080 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
25090 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
250a0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
250b0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
250c0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
250d0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
250e0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77  fault encoding w
250f0 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72  ill be UTF-8 for
25100 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74   databases creat
25110 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69  ed using.** sqli
25120 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
25130 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
25140 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65    ^The default e
25150 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61  ncoding for data
25160 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  bases.** created
25170 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f   using sqlite3_o
25180 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20  pen16() will be 
25190 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
251a0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
251b0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
251c0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
251d0 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
251e0 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
251f0 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
25200 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
25210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
25220 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
25230 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
25240 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
25250 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
25260 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
25270 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
25280 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
25290 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
252a0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
252b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
252c0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
252d0 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
252e0 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
252f0 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
25300 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
25310 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
25320 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
25330 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
25340 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
25350 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
25360 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
25370 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
25380 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
25390 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
253a0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
253b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
253c0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
253d0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
253e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
253f0 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
25400 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
25410 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
25420 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
25430 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
25440 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
25450 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
25460 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
25470 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
25480 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
25490 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
254a0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
254b0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
254c0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
254d0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
254e0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
254f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
25500 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
25510 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
25520 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
25530 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
25540 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
25550 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
25560 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
25570 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
25580 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
25590 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
255a0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
255b0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
255c0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
255d0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
255e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
255f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
25600 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
25610 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
25620 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
25630 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
25640 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
25650 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
25660 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
25670 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
25680 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
25690 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
256a0 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
256b0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
256c0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
256d0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
256e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
256f0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
25700 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
25710 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
25720 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25730 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
25740 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
25750 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
25760 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
25770 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
25780 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
25790 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
257a0 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
257b0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
257c0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
257d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
257e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
257f0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
25800 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
25810 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
25820 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
25830 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
25840 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
25850 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
25860 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
25870 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
25880 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
25890 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
258a0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
258b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
258c0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
258d0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
258e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
258f0 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
25900 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
25910 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
25920 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
25930 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
25940 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
25950 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
25960 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
25970 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
25980 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
25990 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
259a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
259b0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
259c0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
259d0 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
259e0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
259f0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
25a00 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
25a10 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
25a20 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
25a30 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
25a40 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
25a50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
25a60 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
25a70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25a80 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
25a90 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
25aa0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
25ab0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
25ac0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
25ad0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
25ae0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
25af0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
25b00 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
25b10 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
25b20 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
25b30 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
25b40 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
25b50 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
25b60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25b70 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
25b80 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
25b90 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
25ba0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
25bb0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
25bc0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
25bd0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
25be0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
25bf0 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
25c00 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
25c10 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
25c20 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
25c30 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
25c40 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
25c50 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
25c60 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
25c70 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
25c80 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
25c90 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
25ca0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
25cb0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
25cc0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
25cd0 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
25ce0 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
25cf0 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
25d00 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
25d10 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
25d20 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
25d30 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
25d40 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
25d50 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
25d60 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
25d70 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
25d80 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
25d90 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
25da0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
25db0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
25dc0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
25dd0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
25de0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25df0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
25e00 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
25e10 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
25e20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
25e30 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
25e40 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
25e50 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
25e60 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
25e70 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
25e80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
25e90 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
25ea0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
25eb0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
25ec0 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
25ed0 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
25ee0 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
25ef0 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
25f00 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
25f10 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
25f20 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
25f30 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
25f40 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
25f50 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
25f60 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
25f70 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
25f80 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
25f90 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
25fa0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
25fb0 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
25fc0 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
25fd0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
25fe0 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
25ff0 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
26000 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
26010 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
26020 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
26030 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
26040 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
26050 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
26060 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
26070 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
26080 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 55 52 49  e option..** URI
26090 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
260a0 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e  retation is turn
260b0 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66  ed off.** by def
260c0 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65  ault, but future
260d0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
260e0 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65  ite might enable
260f0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   URI filename.**
26100 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
26110 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65  by default.  See
26120 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73   "[URI filenames
26130 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ]" for additiona
26140 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
26150 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65  ..**.** URI file
26160 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64  names are parsed
26170 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46   according to RF
26180 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20  C 3986. ^If the 
26190 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a  URI contains an.
261a0 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68  ** authority, th
261b0 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69  en it must be ei
261c0 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74  ther an empty st
261d0 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69  ring or the stri
261e0 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73  ng .** "localhos
261f0 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68  t". ^If the auth
26200 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20  ority is not an 
26210 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
26220 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20  "localhost", an 
26230 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74  .** error is ret
26240 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c  urned to the cal
26250 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65  ler. ^The fragme
26260 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  nt component of 
26270 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72  a URI, if .** pr
26280 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65  esent, is ignore
26290 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
262a0 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63   uses the path c
262b0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20  omponent of the 
262c0 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20  URI as the name 
262d0 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65  of the disk file
262e0 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69  .** which contai
262f0 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ns the database.
26300 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65   ^If the path be
26310 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20  gins with a '/' 
26320 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74  character, .** t
26330 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70  hen it is interp
26340 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f  reted as an abso
26350 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74  lute path. ^If t
26360 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74  he path does not
26370 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20   begin .** with 
26380 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74  a '/' (meaning t
26390 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74  hat the authorit
263a0 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69  y section is omi
263b0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52  tted from the UR
263c0 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70  I).** then the p
263d0 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ath is interpret
263e0 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65  ed as a relative
263f0 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20   path. .** ^(On 
26400 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72  windows, the fir
26410 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  st component of 
26420 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
26430 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20   .** is a drive 
26440 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65  specification (e
26450 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a  .g. "C:").)^.**.
26460 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75  ** [[core URI qu
26470 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d  ery parameters]]
26480 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f  .** The query co
26490 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
264a0 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72   may contain par
264b0 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65  ameters that are
264c0 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20   interpreted.** 
264d0 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65  either by SQLite
264e0 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61   itself, or by a
264f0 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56   [VFS | custom V
26500 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
26510 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e  n]..** SQLite an
26520 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b  d its built-in [
26530 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74  VFSes] interpret
26540 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   the.** followin
26550 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  g query paramete
26560 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
26570 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
26580 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
26590 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
265a0 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
265b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
265c0 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
265d0 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
265e0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
265f0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
26600 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
26610 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
26620 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
26630 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
26640 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
26650 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
26660 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
26670 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
26680 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
26690 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
266a0 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
266b0 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
266c0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
266d0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
266e0 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
266f0 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
26700 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
26710 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
26720 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
26730 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
26740 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
26750 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
26760 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
26770 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26780 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
26790 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
267a0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
267b0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
267c0 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
267d0 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c  ",.**     "rwc",
267e0 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74   or "memory". At
267f0 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
26800 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
26810 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20  value is.**     
26820 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20  an error)^. .** 
26830 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20      ^If "ro" is 
26840 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
26850 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
26860 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
26870 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63  only .**     acc
26880 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20  ess, just as if 
26890 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
268a0 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20  _READONLY] flag 
268b0 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20  had been set in 
268c0 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72  the .**     thir
268d0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
268e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
268f0 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70   ^If the mode op
26900 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a  tion is set to .
26910 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65  **     "rw", the
26920 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
26930 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
26940 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74  d-write (but not
26950 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20   create) .**    
26960 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53   access, as if S
26970 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
26980 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51  RITE (but not SQ
26990 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
269a0 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65  ) had .**     be
269b0 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22  en set. ^Value "
269c0 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65  rwc" is equivale
269d0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f  nt to setting bo
269e0 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  th .**     SQLIT
269f0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
26a00 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e   and SQLITE_OPEN
26a10 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68  _CREATE.  ^If th
26a20 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
26a30 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22  .**     set to "
26a40 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70  memory" then a p
26a50 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64  ure [in-memory d
26a60 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65  atabase] that ne
26a70 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20  ver reads.**    
26a80 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20   or writes from 
26a90 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49  disk is used. ^I
26aa0 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f  t is an error to
26ab0 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65   specify a value
26ac0 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20   for.**     the 
26ad0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74  mode parameter t
26ae0 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74  hat is less rest
26af0 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61  rictive than tha
26b00 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  t specified by.*
26b10 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20  *     the flags 
26b20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68  passed in the th
26b30 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
26b40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26b50 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
26b60 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
26b70 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
26b80 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
26b90 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
26ba0 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
26bb0 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
26bc0 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
26bd0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
26be0 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
26bf0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
26c00 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
26c10 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
26c20 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
26c30 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
26c40 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
26c50 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
26c60 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
26c70 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
26c80 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
26c90 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
26ca0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
26cb0 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
26cc0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26cd0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
26ce0 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
26cf0 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
26d00 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
26d10 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
26d20 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
26d30 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65  y behavior reque
26d40 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a  sted by setting.
26d50 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
26d60 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
26d70 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  or SQLITE_OPEN_S
26d80 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e  HAREDCACHE flag.
26d90 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
26da0 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70  psow</b>: ^The p
26db0 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e  sow parameter in
26dc0 64 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20  dicates whether 
26dd0 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20  or not the.**   
26de0 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65    [powersafe ove
26df0 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79  rwrite] property
26e00 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f   does or does no
26e10 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a  t apply to the.*
26e20 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65  *     storage me
26e30 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65  dia on which the
26e40 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72   database file r
26e50 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c  esides..**.**  <
26e60 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62  li> <b>nolock</b
26e70 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70  >: ^The nolock p
26e80 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
26e90 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61  olean query para
26ea0 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69  meter.**     whi
26eb0 63 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c  ch if set disabl
26ec0 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20  es file locking 
26ed0 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  in rollback jour
26ee0 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73  nal modes.  This
26ef0 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75  .**     is usefu
26f00 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20  l for accessing 
26f10 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20  a database on a 
26f20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20  filesystem that 
26f30 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20  does not.**     
26f40 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e  support locking.
26f50 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61    Caution:  Data
26f60 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20  base corruption 
26f70 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
26f80 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f  two.**     or mo
26f90 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69  re processes wri
26fa0 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  te to the same d
26fb0 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20  atabase and any 
26fc0 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20  one of those.** 
26fd0 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73      processes us
26fe0 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a  es nolock=1..**.
26ff0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75  **  <li> <b>immu
27000 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  table</b>: ^The 
27010 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65  immutable parame
27020 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
27030 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61   query.**     pa
27040 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64  rameter that ind
27050 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20  icates that the 
27060 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
27070 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20   stored on.**   
27080 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69    read-only medi
27090 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61  a.  ^When immuta
270a0 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69  ble is set, SQLi
270b0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
270c0 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62  the.**     datab
270d0 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  ase file cannot 
270e0 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e  be changed, even
270f0 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69   by a process wi
27100 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20  th higher.**    
27110 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20   privilege, and 
27120 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  so the database 
27130 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f  is opened read-o
27140 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b  nly and all lock
27150 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63  ing.**     and c
27160 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20  hange detection 
27170 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61  is disabled.  Ca
27180 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74  ution: Setting t
27190 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20  he immutable.** 
271a0 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20      property on 
271b0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
271c0 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63  that does in fac
271d0 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73  t change can res
271e0 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e  ult.**     in in
271f0 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65  correct query re
27200 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51  sults and/or [SQ
27210 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72  LITE_CORRUPT] er
27220 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65  rors..**     See
27230 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
27240 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e  OCAP_IMMUTABLE].
27250 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f  .**       .** </
27260 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
27270 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
27280 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
27290 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
272a0 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
272b0 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
272c0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
272d0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
272e0 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
272f0 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
27300 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
27310 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
27320 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
27330 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
27340 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
27350 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
27360 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
27370 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
27380 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
27390 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
273a0 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
273b0 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
273c0 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
273d0 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
273e0 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
273f0 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
27400 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
27410 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
27420 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
27430 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
27440 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
27450 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
27460 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
27470 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
27480 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
27490 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
274a0 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
274b0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
274c0 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
274d0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
274e0 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
274f0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
27500 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
27510 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
27520 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
27530 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
27540 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
27550 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
27560 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
27570 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
27580 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
27590 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
275a0 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
275b0 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
275c0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
275d0 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
275e0 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
275f0 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
27600 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
27610 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
27620 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
27630 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
27640 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
27650 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
27660 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
27670 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
27680 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
27690 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
276a0 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
276b0 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
276c0 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
276d0 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
276e0 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
276f0 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
27700 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
27710 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
27720 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
27730 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
27740 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
27750 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
27760 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
27770 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
27780 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
27790 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
277a0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
277b0 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
277c0 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
277d0 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
277e0 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
277f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
27800 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
27810 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f  a.db?vfs=unix-do
27820 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20  tfile <td>.**   
27830 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
27840 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
27850 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
27860 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
27870 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20  -dotfile".**    
27880 20 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20        that uses 
27890 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61  dot-files in pla
278a0 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69  ce of posix advi
278b0 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a  sory locking..**
278c0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
278d0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
278e0 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
278f0 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
27900 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
27910 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
27920 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
27930 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
27940 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
27950 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
27960 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
27970 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
27980 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
27990 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
279a0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
279b0 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
279c0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
279d0 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
279e0 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
279f0 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
27a00 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
27a10 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
27a20 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
27a30 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
27a40 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
27a50 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
27a60 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
27a70 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
27a80 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
27a90 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
27aa0 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
27ab0 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
27ac0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
27ad0 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
27ae0 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
27af0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
27b00 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
27b10 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
27b20 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
27b30 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
27b40 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
27b50 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
27b60 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
27b70 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
27b80 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
27b90 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
27ba0 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
27bb0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
27bc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
27bd0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
27be0 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
27bf0 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
27c00 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
27c10 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
27c20 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
27c30 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
27c40 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
27c50 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
27c60 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
27c70 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
27c80 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
27c90 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
27ca0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27cb0 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  )..**.** <b>Note
27cc0 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74   to Windows Runt
27cd0 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ime users:</b>  
27ce0 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69  The temporary di
27cf0 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20  rectory must be 
27d00 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  set.** prior to 
27d10 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
27d20 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
27d30 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74  3_open_v2().  Ot
27d40 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73  herwise, various
27d50 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61  .** features tha
27d60 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73  t require the us
27d70 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66  e of temporary f
27d80 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a  iles may fail..*
27d90 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
27da0 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
27db0 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73  ectory].*/.int s
27dc0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
27dd0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
27de0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
27df0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
27e00 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
27e10 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
27e20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
27e30 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
27e40 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
27e50 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
27e60 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
27e70 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
27e80 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
27e90 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
27ea0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
27eb0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
27ec0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
27ed0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
27ee0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
27ef0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
27f00 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
27f10 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
27f20 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
27f30 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
27f40 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
27f50 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
27f60 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
27f70 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
27f80 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
27f90 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
27fa0 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
27fb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27fc0 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46   Obtain Values F
27fd0 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72  or URI Parameter
27fe0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  s.**.** These ar
27ff0 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e  e utility routin
28000 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46  es, useful to VF
28010 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
28020 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a  s, that check.**
28030 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74   to see if a dat
28040 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61  abase file was a
28050 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69   URI that contai
28060 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71  ned a specific q
28070 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74  uery .** paramet
28080 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62  er, and if so ob
28090 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20  tains the value 
280a0 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61  of that query pa
280b0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
280c0 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62  f F is the datab
280d0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69  ase filename poi
280e0 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f  nter passed into
280f0 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74   the xOpen() met
28100 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53  hod of .** a VFS
28110 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28120 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70  when the flags p
28130 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
28140 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a  n() has one or .
28150 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
28160 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
28170 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e   or [SQLITE_OPEN
28180 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73  _MAIN_DB] bits s
28190 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74  et and.** P is t
281a0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71  he name of the q
281b0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20  uery parameter, 
281c0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
281d0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
281e0 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  P) returns the v
281f0 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a  alue of the P.**
28200 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74   parameter if it
28210 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c   exists or a NUL
28220 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64  L pointer if P d
28230 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61  oes not appear a
28240 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61  s a .** query pa
28250 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49  rameter on F.  I
28260 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70  f P is a query p
28270 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a  arameter of F.**
28280 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74   has no explicit
28290 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c   value, then sql
282a0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
282b0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a  er(F,P) returns.
282c0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
282d0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
282e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
282f0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
28300 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73  ,P,B) routine as
28310 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20  sumes that P is 
28320 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72  a boolean.** par
28330 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
28340 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66  ns true (1) or f
28350 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69  alse (0) accordi
28360 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a  ng to the value.
28370 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71  ** of P.  The sq
28380 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
28390 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
283a0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
283b0 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ) if the.** valu
283c0 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d  e of query param
283d0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
283e0 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20   "yes", "true", 
283f0 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a  or "on" in any.*
28400 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65  * case or if the
28410 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
28420 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75  th a non-zero nu
28430 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73  mber.  The .** s
28440 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
28450 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
28460 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  es returns false
28470 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75   (0) if the valu
28480 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61  e of.** query pa
28490 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
284a0 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65   of "no", "false
284b0 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61  ", or "off" in a
284c0 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66  ny case or.** if
284d0 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
284e0 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63  s with a numeric
284f0 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20   zero.  If P is 
28500 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70  not a query.** p
28510 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72  arameter on F or
28520 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
28530 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d   P is does not m
28540 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a  atch any of the.
28550 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73  ** above, then s
28560 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
28570 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
28580 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  s (B!=0)..**.** 
28590 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
285a0 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75  int64(F,P,D) rou
285b0 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68  tine converts th
285c0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74  e value of P int
285d0 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69  o a.** 64-bit si
285e0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
285f0 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e   returns that in
28600 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50  teger, or D if P
28610 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69   does not.** exi
28620 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75  st.  If the valu
28630 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68  e of P is someth
28640 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61  ing other than a
28650 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a  n integer, then.
28660 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  ** zero is retur
28670 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46  ned..** .** If F
28680 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
28690 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  er, then sqlite3
286a0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
286b0 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,P) returns NULL
286c0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
286d0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
286e0 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49  B) returns B.  I
286f0 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c  f F is not a NUL
28700 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a  L pointer and.**
28710 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
28720 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  se file pathname
28730 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51   pointer that SQ
28740 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f  Lite passed into
28750 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46   the xOpen.** VF
28760 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  S method, then t
28770 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
28780 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
28790 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
287a0 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72  bably.** undesir
287b0 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  able..*/.const c
287c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69  har *sqlite3_uri
287d0 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74  _parameter(const
287e0 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
287f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
28800 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74  aram);.int sqlit
28810 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63  e3_uri_boolean(c
28820 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
28830 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50  , const char *zP
28840 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75  aram, int bDefau
28850 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  lt);.sqlite3_int
28860 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  64 sqlite3_uri_i
28870 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a  nt64(const char*
28880 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
28890 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
288a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
288b0 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
288c0 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54   Messages.** MET
288d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
288e0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
288f0 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a  recent sqlite3_*
28900 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69   API call associ
28910 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64  ated with .** [d
28920 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28930 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68  on] D failed, th
28940 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  en the sqlite3_e
28950 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66  rrcode(D) interf
28960 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ace.** returns t
28970 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
28980 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  lt code] or [ext
28990 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
289a0 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41  e] for that.** A
289b0 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74  PI call..** If t
289c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
289d0 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63  PI call was succ
289e0 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20  essful,.** then 
289f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
28a00 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72   from sqlite3_er
28a10 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
28a20 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ined..** ^The sq
28a30 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
28a40 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
28a50 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
28a60 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
28a70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
28a80 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
28a90 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
28aa0 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
28ab0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
28ac0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
28ad0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28ae0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
28af0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
28b00 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
28b10 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
28b20 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
28b30 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
28b40 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
28b50 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
28b60 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
28b70 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
28b80 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
28b90 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
28ba0 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
28bb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
28bc0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
28bd0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
28be0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
28bf0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
28c00 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
28c10 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
28c20 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
28c30 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
28c40 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
28c50 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
28c60 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
28c70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
28c80 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
28c90 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
28ca0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
28cb0 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
28cc0 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
28cd0 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
28ce0 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
28cf0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
28d00 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
28d10 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
28d20 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
28d30 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
28d40 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
28d50 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
28d60 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
28d70 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
28d80 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
28d90 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
28da0 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
28db0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
28dc0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
28dd0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
28de0 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
28df0 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
28e00 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
28e10 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
28e20 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
28e30 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
28e40 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
28e50 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
28e60 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
28e70 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
28e80 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
28e90 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
28ea0 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
28eb0 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
28ec0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
28ed0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
28ee0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
28ef0 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
28f00 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
28f10 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
28f20 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
28f30 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
28f40 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
28f50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
28f60 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
28f70 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
28f80 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
28f90 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
28fa0 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
28fb0 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
28fc0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
28fd0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
28fe0 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
28ff0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
29000 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
29010 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
29020 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
29030 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
29040 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
29050 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
29060 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
29070 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
29080 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
29090 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
290a0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  ;.int sqlite3_ex
290b0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
290c0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e  qlite3 *db);.con
290d0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
290e0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
290f0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
29100 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
29110 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
29120 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
29130 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
29140 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65  ** CAPI3REF: Pre
29150 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
29160 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
29170 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
29180 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
29190 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
291a0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
291b0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
291c0 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
291d0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
291e0 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65  t that.** has be
291f0 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  en compiled into
29200 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64   binary form and
29210 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20   is ready to be 
29220 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  evaluated..**.**
29230 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53   Think of each S
29240 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
29250 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75  a separate compu
29260 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68  ter program.  Th
29270 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
29280 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65  L text is source
29290 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72   code.  A prepar
292a0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
292b0 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63  ect .** is the c
292c0 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63  ompiled object c
292d0 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75  ode.  All SQL mu
292e0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
292f0 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72  into a.** prepar
29300 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66  ed statement bef
29310 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75  ore it can be ru
29320 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  n..**.** The lif
29330 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65  e-cycle of a pre
29340 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29350 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67  object usually g
29360 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  oes like this:.*
29370 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
29380 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65  > Create the pre
29390 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
293a0 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
293b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
293c0 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ()]..** <li> Bin
293d0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72  d values to [par
293e0 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
293f0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
29400 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
29410 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
29420 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
29430 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
29440 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
29450 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
29460 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65  i> Reset the pre
29470 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
29480 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
29490 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
294a0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
294b0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
294c0 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
294d0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
294e0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
294f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
29500 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
29510 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  /ol>.*/.typedef 
29520 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
29530 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
29540 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29550 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
29560 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ts.** METHOD: sq
29570 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lite3.**.** ^(Th
29580 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
29590 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
295a0 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
295b0 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
295c0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
295d0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
295e0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
295f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
29600 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
29610 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
29620 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
29630 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
29640 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
29650 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
29660 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
29670 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
29680 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
29690 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
296a0 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
296b0 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
296c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
296d0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
296e0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
296f0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
29700 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
29710 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
29720 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
29730 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
29740 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
29750 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
29760 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
29770 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
29780 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
29790 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
297a0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
297b0 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
297c0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
297d0 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
297e0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
297f0 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
29800 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
29810 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
29820 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
29830 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
29840 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
29850 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
29860 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
29870 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
29880 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
29890 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
298a0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
298b0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
298c0 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
298d0 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
298e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
298f0 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
29900 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
29910 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
29920 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
29930 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
29940 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
29950 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
29960 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
29970 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
29980 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
29990 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
299a0 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
299b0 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
299c0 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
299d0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
299e0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
299f0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
29a00 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
29a10 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
29a20 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
29a30 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
29a40 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
29a50 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
29a60 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
29a70 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
29a80 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
29a90 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
29aa0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
29ab0 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
29ac0 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
29ad0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
29ae0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
29af0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
29b00 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
29b10 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
29b20 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
29b30 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
29b40 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
29b50 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
29b60 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
29b70 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
29b80 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
29b90 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
29ba0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
29bb0 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
29bc0 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
29bd0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
29be0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
29bf0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
29c00 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
29c10 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
29c20 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
29c30 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
29c40 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
29c50 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
29c60 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
29c70 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
29c80 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
29c90 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
29ca0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
29cb0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
29cc0 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
29cd0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
29ce0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
29cf0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
29d00 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
29d10 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
29d20 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
29d30 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
29d40 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
29d50 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
29d60 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
29d70 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
29d80 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
29d90 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
29da0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
29db0 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
29dc0 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
29dd0 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
29de0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
29df0 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
29e00 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
29e10 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
29e20 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
29e30 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
29e40 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
29e50 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
29e60 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
29e70 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
29e80 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
29e90 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
29ea0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
29eb0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
29ec0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
29ed0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
29ee0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
29ef0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
29f00 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
29f10 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
29f20 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
29f30 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29f40 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
29f50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
29f60 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
29f70 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29f80 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
29f90 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
29fa0 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
29fb0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29fc0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
29fd0 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
29fe0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
29ff0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2a000 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2a010 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
2a020 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
2a030 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
2a040 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
2a050 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
2a060 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
2a070 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
2a080 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
2a090 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
2a0a0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
2a0b0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2a0c0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2a0d0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
2a0e0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2a0f0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2a100 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
2a110 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
2a120 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
2a130 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
2a140 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a150 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
2a160 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
2a170 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
2a180 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
2a190 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2a1a0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
2a1b0 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
2a1c0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
2a1d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2a1e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
2a1f0 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
2a200 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
2a210 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2a220 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2a230 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
2a240 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
2a250 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
2a260 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
2a270 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2a280 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  t.  If [sqlite3_
2a290 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2a2a0 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c 65  .** the equivale
2a2b0 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c 6f  nt tries to allo
2a2c0 63 61 74 65 20 73 70 61 63 65 20 66 6f 72 20 6d  cate space for m
2a2d0 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d 61  ore than this ma
2a2e0 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 6e  ny opcodes.** in
2a2f0 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61 72   a single prepar
2a300 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 6e  ed statement, an
2a310 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 72   SQLITE_NOMEM er
2a320 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
2a330 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2a340 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
2a350 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
2a360 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
2a370 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
2a380 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2a390 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
2a3a0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
2a3b0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
2a3c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2a3d0 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
2a3e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a3f0 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
2a400 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2a410 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
2a420 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
2a430 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
2a440 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
2a450 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
2a460 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
2a470 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2a480 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
2a490 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
2a4a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
2a4b0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
2a4c0 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
2a4d0 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
2a4e0 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
2a4f0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
2a500 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2a510 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2a520 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
2a530 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2a540 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
2a550 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a560 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
2a570 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
2a580 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
2a590 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
2a5a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
2a5b0 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
2a5c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
2a5d0 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
2a5e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a5f0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
2a600 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
2a610 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
2a620 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2a630 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2a640 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
2a650 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
2a660 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
2a670 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
2a680 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
2a690 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
2a6a0 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
2a6b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a6c0 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
2a6d0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
2a6e0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
2a6f0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
2a700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a710 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
2a720 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
2a730 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
2a740 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
2a750 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
2a760 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
2a770 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
2a780 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
2a790 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
2a7a0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
2a7b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
2a7c0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
2a7d0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
2a7e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
2a7f0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
2a800 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
2a810 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
2a820 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
2a830 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
2a840 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2a850 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
2a860 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
2a870 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2a880 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
2a890 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
2a8a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2a8b0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2a8c0 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
2a8d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2a8e0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
2a8f0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
2a900 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a910 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
2a920 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
2a930 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a940 20 50 72 65 70 61 72 65 20 46 6c 61 67 73 0a 2a   Prepare Flags.*
2a950 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2a960 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
2a970 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74 20 63  ous flags that c
2a980 61 6e 20 62 65 20 70 61 73 73 65 64 20 69 6e 74  an be passed int
2a990 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 22  o.** "prepFlags"
2a9a0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
2a9b0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
2a9c0 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a 20  re_v3()] and.** 
2a9d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a9e0 31 36 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 61  16_v3()] interfa
2a9f0 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 66  ces..**.** New f
2aa00 6c 61 67 73 20 6d 61 79 20 62 65 20 61 64 64 65  lags may be adde
2aa10 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
2aa20 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
2aa30 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
2aa40 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50  SQLITE_PREPARE_P
2aa50 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c 64  ERSISTENT]] ^(<d
2aa60 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  t>SQLITE_PREPARE
2aa70 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 3e  _PERSISTENT</dt>
2aa80 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c 49  .** <dd>The SQLI
2aa90 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49  TE_PREPARE_PERSI
2aaa0 53 54 45 4e 54 20 66 6c 61 67 20 69 73 20 61 20  STENT flag is a 
2aab0 68 69 6e 74 20 74 6f 20 74 68 65 20 71 75 65 72  hint to the quer
2aac0 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 61  y planner.** tha
2aad0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
2aae0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
2aaf0 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 61 20   retained for a 
2ab00 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a 2a  long time and.**
2ab10 20 70 72 6f 62 61 62 6c 79 20 72 65 75 73 65 64   probably reused
2ab20 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 5e   many times.)^ ^
2ab30 57 69 74 68 6f 75 74 20 74 68 69 73 20 66 6c 61  Without this fla
2ab40 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  g, [sqlite3_prep
2ab50 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e 64  are_v3()].** and
2ab60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ab70 65 31 36 5f 76 33 28 29 5d 20 61 73 73 75 6d 65  e16_v3()] assume
2ab80 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72   that the prepar
2ab90 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  ed statement wil
2aba0 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a 75  l .** be used ju
2abb0 73 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d 6f  st once or at mo
2abc0 73 74 20 61 20 66 65 77 20 74 69 6d 65 73 20 61  st a few times a
2abd0 6e 64 20 74 68 65 6e 20 64 65 73 74 72 6f 79 65  nd then destroye
2abe0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2abf0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2ac00 72 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e 2e  relatively soon.
2ac10 20 54 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   The current imp
2ac20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 73  lementation acts
2ac30 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  .** on this hint
2ac40 20 62 79 20 61 76 6f 69 64 69 6e 67 20 74 68 65   by avoiding the
2ac50 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 69   use of [lookasi
2ac60 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 73  de memory] so as
2ac70 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c 65   not to.** deple
2ac80 74 65 20 74 68 65 20 6c 69 6d 69 74 65 64 20 73  te the limited s
2ac90 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  tore of lookasid
2aca0 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 65  e memory. Future
2acb0 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a 20   versions of.** 
2acc0 53 51 4c 69 74 65 20 6d 61 79 20 61 63 74 20 6f  SQLite may act o
2acd0 6e 20 74 68 69 73 20 68 69 6e 74 20 64 69 66 66  n this hint diff
2ace0 65 72 65 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c  erently..** </dl
2acf0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
2ad00 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2ad10 49 53 54 45 4e 54 20 20 20 20 20 20 20 20 20 20  ISTENT          
2ad20 20 20 20 20 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 20      0x01../*.** 
2ad30 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
2ad40 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
2ad50 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ment.** KEYWORDS
2ad60 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
2ad70 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45   compiler}.** ME
2ad80 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
2ad90 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71   CONSTRUCTOR: sq
2ada0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2adb0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
2adc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 74  QL statement, it
2add0 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
2ade0 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
2adf0 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
2ae00 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
2ae10 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2ae20 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65 72 20 77    Or, in other w
2ae30 6f 72 64 73 2c 20 74 68 65 73 65 20 72 6f 75 74  ords, these rout
2ae40 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63 6f 6e 73  ines.** are cons
2ae50 74 72 75 63 74 6f 72 73 20 66 6f 72 20 74 68 65  tructors for the
2ae60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ae70 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ment] object..**
2ae80 0a 2a 2a 20 54 68 65 20 70 72 65 66 65 72 72 65  .** The preferre
2ae90 64 20 72 6f 75 74 69 6e 65 20 74 6f 20 75 73 65  d routine to use
2aea0 20 69 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   is [sqlite3_pre
2aeb0 70 61 72 65 5f 76 32 28 29 5d 2e 20 20 54 68 65  pare_v2()].  The
2aec0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2aed0 70 61 72 65 28 29 5d 20 69 6e 74 65 72 66 61 63  pare()] interfac
2aee0 65 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20  e is legacy and 
2aef0 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65  should be avoide
2af00 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  d..** [sqlite3_p
2af10 72 65 70 61 72 65 5f 76 33 28 29 5d 20 68 61 73  repare_v3()] has
2af20 20 61 6e 20 65 78 74 72 61 20 22 70 72 65 70 46   an extra "prepF
2af30 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20 74 68 61  lags" option tha
2af40 74 20 69 73 20 75 73 65 64 0a 2a 2a 20 66 6f 72  t is used.** for
2af50 20 73 70 65 63 69 61 6c 20 70 75 72 70 6f 73 65   special purpose
2af60 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 73 65  s..**.** The use
2af70 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 69 6e   of the UTF-8 in
2af80 74 65 72 66 61 63 65 73 20 69 73 20 70 72 65 66  terfaces is pref
2af90 65 72 72 65 64 2c 20 61 73 20 53 51 4c 69 74 65  erred, as SQLite
2afa0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 6f   currently.** do
2afb0 65 73 20 61 6c 6c 20 70 61 72 73 69 6e 67 20 75  es all parsing u
2afc0 73 69 6e 67 20 55 54 46 2d 38 2e 20 20 54 68 65  sing UTF-8.  The
2afd0 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61 63   UTF-16 interfac
2afe0 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
2aff0 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65 6e 69 65  ** as a convenie
2b000 6e 63 65 2e 20 20 54 68 65 20 55 54 46 2d 31 36  nce.  The UTF-16
2b010 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b   interfaces work
2b020 20 62 79 20 63 6f 6e 76 65 72 74 69 6e 67 20 74   by converting t
2b030 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74 65 78 74  he.** input text
2b040 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20 74 68 65   into UTF-8, the
2b050 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63  n invoking the c
2b060 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 55 54 46  orresponding UTF
2b070 2d 38 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  -8 interface..**
2b080 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
2b090 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73  gument, "db", is
2b0a0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2b0b0 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65  nection] obtaine
2b0c0 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f  d from a.** prio
2b0d0 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
2b0e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  l to [sqlite3_op
2b0f0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
2b100 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a  open_v2()] or.**
2b110 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2b120 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61  ()].  The databa
2b130 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
2b140 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e  st not have been
2b150 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   closed..**.** T
2b160 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2b170 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74  nt, "zSql", is t
2b180 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  he statement to 
2b190 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63  be compiled, enc
2b1a0 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65  oded.** as eithe
2b1b0 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
2b1c0 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  6.  The sqlite3_
2b1d0 70 72 65 70 61 72 65 28 29 2c 20 73 71 6c 69 74  prepare(), sqlit
2b1e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c  e3_prepare_v2(),
2b1f0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
2b200 70 72 65 70 61 72 65 5f 76 33 28 29 0a 2a 2a 20  prepare_v3().** 
2b210 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
2b220 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
2b230 33 5f 70 72 65 70 61 72 65 31 36 28 29 2c 20 73  3_prepare16(), s
2b240 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b250 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71  _v2(),.** and sq
2b260 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b270 76 33 28 29 20 75 73 65 20 55 54 46 2d 31 36 2e  v3() use UTF-16.
2b280 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
2b290 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
2b2a0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2b2b0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
2b2c0 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
2b2d0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2b2e0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f   ^If nByte is po
2b2f0 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  sitive, then it 
2b300 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2b310 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66   of bytes read f
2b320 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e  rom zSql.  ^If n
2b330 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68  Byte is zero, th
2b340 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a  en no prepared.*
2b350 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67  * statement is g
2b360 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20  enerated..** If 
2b370 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
2b380 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
2b390 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
2b3a0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
2b3b0 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20  n.** there is a 
2b3c0 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63  small performanc
2b3d0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70  e advantage to p
2b3e0 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
2b3f0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
2b400 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2b410 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2b420 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
2b430 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
2b440 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
2b450 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  tor..**.** ^If p
2b460 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
2b470 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
2b480 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
2b490 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
2b4a0 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
2b4b0 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
2b4c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
2b4d0 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
2b4e0 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
2b4f0 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
2b500 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
2b510 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
2b520 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
2b530 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
2b540 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
2b550 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
2b560 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
2b570 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
2b580 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b590 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
2b5a0 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
2b5b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
2b5c0 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
2b5d0 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
2b5e0 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
2b5f0 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
2b600 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
2b610 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
2b620 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
2b630 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
2b640 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
2b650 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
2b660 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
2b670 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
2b680 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
2b690 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
2b6a0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
2b6b0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
2b6c0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2b6d0 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
2b6e0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2b6f0 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
2b700 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
2b710 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
2b720 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
2b730 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
2b740 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
2b750 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
2b760 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
2b770 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2b780 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
2b790 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2b7a0 72 65 5f 76 32 28 29 2c 20 73 71 6c 69 74 65 33  re_v2(), sqlite3
2b7b0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 2c 20 73  _prepare_v3(), s
2b7c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b7d0 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71  _v2(),.** and sq
2b7e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b7f0 76 33 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v3() interfaces 
2b800 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  are recommended 
2b810 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
2b820 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c 64  rams..** The old
2b830 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73  er interfaces (s
2b840 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2b850 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2b860 70 61 72 65 31 36 28 29 29 0a 2a 2a 20 61 72 65  pare16()).** are
2b870 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61   retained for ba
2b880 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
2b890 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
2b8a0 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
2b8b0 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ged..** ^In the 
2b8c0 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "vX" interfaces,
2b8d0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2b8e0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
2b8f0 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
2b900 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2b910 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
2b920 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2b930 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
2b940 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
2b950 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2b960 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
2b970 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66  to.** behave dif
2b980 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65  ferently in thre
2b990 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e ways:.**.** <o
2b9a0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  l>.** <li>.** ^I
2b9b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
2b9c0 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
2b9d0 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
2b9e0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
2b9f0 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
2ba00 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
2ba10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2ba20 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
2ba30 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
2ba40 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
2ba50 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
2ba60 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d  n it again. As m
2ba70 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d  any as [SQLITE_M
2ba80 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d  AX_SCHEMA_RETRY]
2ba90 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c  .** retries will
2baa0 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71   occur before sq
2bab0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76  lite3_step() giv
2bac0 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e  es up and return
2bad0 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c  s an error..** <
2bae0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
2baf0 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
2bb00 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
2bb10 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
2bb20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
2bb30 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
2bb40 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
2bb50 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
2bb60 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
2bb70 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
2bb80 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
2bb90 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
2bba0 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
2bbb0 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
2bbc0 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
2bbd0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
2bbe0 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
2bbf0 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
2bc00 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
2bc10 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
2bc20 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2bc30 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
2bc40 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
2bc50 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
2bc60 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
2bc70 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
2bc80 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
2bc90 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
2bca0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
2bcb0 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
2bcc0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
2bcd0 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63  ^If the specific
2bce0 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20   value bound to 
2bcf0 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73  [parameter | hos
2bd00 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  t parameter] in 
2bd10 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c  the .** WHERE cl
2bd20 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75  ause might influ
2bd30 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20  ence the choice 
2bd40 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  of query plan fo
2bd50 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a  r a statement,.*
2bd60 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  * then the state
2bd70 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74  ment will be aut
2bd80 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
2bd90 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65  piled, as if the
2bda0 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20  re had been .** 
2bdb0 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c  a schema change,
2bdc0 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b   on the first  [
2bdd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2bde0 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  call following a
2bdf0 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20  ny change.** to 
2be00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2be10 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
2be20 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61  s] of that [para
2be30 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65  meter]. .** ^The
2be40 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
2be50 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20  of WHERE-clause 
2be60 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68  [parameter] migh
2be70 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
2be80 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75  .** choice of qu
2be90 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20  ery plan if the 
2bea0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2beb0 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
2bec0 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f  of a [LIKE].** o
2bed0 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  r [GLOB] operato
2bee0 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61  r or if the para
2bef0 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65  meter is compare
2bf00 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20  d to an indexed 
2bf10 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68  column.** and th
2bf20 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
2bf30 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d  _STAT3] compile-
2bf40 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
2bf50 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e  nabled..** </li>
2bf60 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
2bf70 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65 70  <p>^sqlite3_prep
2bf80 61 72 65 5f 76 33 28 29 20 64 69 66 66 65 72 73  are_v3() differs
2bf90 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70 72   from sqlite3_pr
2bfa0 65 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79 20  epare_v2() only 
2bfb0 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68 65  in having.** the
2bfc0 20 65 78 74 72 61 20 70 72 65 70 46 6c 61 67 73   extra prepFlags
2bfd0 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63   parameter, whic
2bfe0 68 20 69 73 20 61 20 62 69 74 20 61 72 72 61 79  h is a bit array
2bff0 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 7a   consisting of z
2c000 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 6f  ero or.** more o
2c010 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50 52  f the [SQLITE_PR
2c020 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2c030 7c 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f  |SQLITE_PREPARE_
2c040 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65 0a  *] flags.  ^The.
2c050 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
2c060 72 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  re_v2() interfac
2c070 65 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20  e works exactly 
2c080 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73  the same as.** s
2c090 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c0a0 33 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f 20  3() with a zero 
2c0b0 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d 65  prepFlags parame
2c0c0 74 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ter..*/.int sqli
2c0d0 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
2c0e0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2c0f0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2c100 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2c110 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2c120 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2c130 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2c140 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2c150 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2c160 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2c170 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2c180 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2c190 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2c1a0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2c1b0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2c1c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
2c1d0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2c1e0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2c1f0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2c200 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2c210 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c220 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2c230 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2c240 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2c250 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2c260 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2c270 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2c280 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2c290 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2c2a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2c2b0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2c2c0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2c2d0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2c2e0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2c2f0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2c300 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2c310 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2c320 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2c330 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2c340 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2c350 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2c360 70 61 72 65 5f 76 33 28 0a 20 20 73 71 6c 69 74  pare_v3(.  sqlit
2c370 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2c380 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2c390 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2c3a0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2c3b0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2c3c0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2c3d0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2c3e0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2c3f0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2c400 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2c410 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65  es. */.  unsigne
2c420 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c  d int prepFlags,
2c430 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65   /* Zero or more
2c440 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f   SQLITE_PREPARE_
2c450 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69   flags */.  sqli
2c460 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2c470 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2c480 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2c490 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
2c4a0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2c4b0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2c4c0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2c4d0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
2c4e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2c4f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2c500 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2c510 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2c520 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2c530 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2c540 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2c550 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
2c560 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2c570 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2c580 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2c590 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2c5a0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2c5b0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2c5c0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2c5d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2c5e0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
2c5f0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2c600 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2c610 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2c620 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2c630 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69  are16_v2(.  sqli
2c640 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2c650 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2c660 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2c670 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
2c680 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2c690 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
2c6a0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2c6b0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2c6c0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2c6d0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2c6e0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2c6f0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2c700 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2c710 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2c720 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
2c730 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2c740 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2c750 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2c760 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
2c770 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2c780 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  3(.  sqlite3 *db
2c790 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2c7a0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2c7b0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2c7c0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2c7d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2c7e0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2c7f0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2c800 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2c810 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2c820 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2c830 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  /.  unsigned int
2c840 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a   prepFlags, /* Z
2c850 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49  ero or more SQLI
2c860 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67  TE_PREPARE_ flag
2c870 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  s */.  sqlite3_s
2c880 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2c890 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2c8a0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2c8b0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2c8c0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2c8d0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2c8e0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2c8f0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
2c900 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
2c910 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
2c920 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2c930 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2c940 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29  e sqlite3_sql(P)
2c950 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c960 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2c970 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55 54  a copy of the UT
2c980 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  F-8.** SQL text 
2c990 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 5b  used to create [
2c9a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c9b0 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a 2a  nt] P if P was.*
2c9c0 2a 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71  * created by [sq
2c9d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2c9e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
2c9f0 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20  epare_v3()],.** 
2ca00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ca10 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 5b 73 71  16_v2()], or [sq
2ca20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2ca30 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  v3()]..** ^The s
2ca40 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2ca50 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65  sql(P) interface
2ca60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2ca70 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a  er to a UTF-8.**
2ca80 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
2ca90 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78 74 20  ng the SQL text 
2caa0 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  of prepared stat
2cab0 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20  ement P with.** 
2cac0 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
2cad0 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a  s] expanded..**.
2cae0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2caf0 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20  , if a prepared 
2cb00 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65  statement is cre
2cb10 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  ated using the S
2cb20 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45  QL.** text "SELE
2cb30 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e  CT $abc,:xyz" an
2cb40 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24  d if parameter $
2cb50 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20  abc is bound to 
2cb60 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20  integer 2345.** 
2cb70 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78  and parameter :x
2cb80 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74  yz is unbound, t
2cb90 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  hen sqlite3_sql(
2cba0 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ) will return.**
2cbb0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2cbc0 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61  ring, "SELECT $a
2cbd0 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c  bc,:xyz" but sql
2cbe0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2cbf0 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  l().** will retu
2cc00 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c  rn "SELECT 2345,
2cc10 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  NULL".)^.**.** ^
2cc20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61  The sqlite3_expa
2cc30 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72  nded_sql() inter
2cc40 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c  face returns NUL
2cc50 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
2cc60 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61  t memory.** is a
2cc70 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64  vailable to hold
2cc80 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20   the result, or 
2cc90 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f  if the result wo
2cca0 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a  uld exceed the.*
2ccb0 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74  * the maximum st
2ccc0 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65  ring length dete
2ccd0 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53  rmined by the [S
2cce0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2ccf0 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  TH]..**.** ^The 
2cd00 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
2cd10 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
2cd20 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69  e-time option li
2cd30 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66  mits the size of
2cd40 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65  .** bound parame
2cd50 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20  ter expansions. 
2cd60 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d   ^The [SQLITE_OM
2cd70 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c  IT_TRACE] compil
2cd80 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
2cd90 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f   causes sqlite3_
2cda0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74  expanded_sql() t
2cdb0 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  o always return 
2cdc0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2cdd0 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64   string returned
2cde0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28   by sqlite3_sql(
2cdf0 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20 62 79  P) is managed by
2ce00 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a   SQLite and is.*
2ce10 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
2ce20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70  freed when the p
2ce30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ce40 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a  t is finalized..
2ce50 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72  ** ^The string r
2ce60 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2ce70 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2ce80 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72  P), on the other
2ce90 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74   hand,.** is obt
2cea0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2ceb0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
2cec0 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 20 62  d must be free b
2ced0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
2cee0 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20  n.** by passing 
2cef0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  it to [sqlite3_f
2cf00 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ree()]..*/.const
2cf10 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
2cf20 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
2cf30 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73  *pStmt);.char *s
2cf40 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2cf50 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
2cf60 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2cf70 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
2cf80 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
2cf90 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
2cfa0 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20  The Database.** 
2cfb0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2cfc0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2cfd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2cfe0 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
2cff0 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2d000 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
2d010 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
2d020 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d030 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
2d040 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
2d050 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
2d060 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
2d070 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
2d080 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
2d090 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2d0a0 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
2d0b0 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
2d0c0 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
2d0d0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
2d0e0 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
2d0f0 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
2d100 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2d110 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2d120 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
2d130 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
2d140 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
2d150 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
2d160 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2d170 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
2d180 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
2d190 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
2d1a0 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
2d1b0 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
2d1c0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
2d1d0 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
2d1e0 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
2d1f0 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
2d200 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2d210 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
2d220 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
2d230 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2d240 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
2d250 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
2d260 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
2d270 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2d280 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
2d290 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
2d2a0 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
2d2b0 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
2d2c0 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
2d2d0 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
2d2e0 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
2d2f0 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
2d300 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
2d310 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2d320 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
2d330 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
2d340 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
2d350 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
2d360 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
2d370 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
2d380 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
2d390 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
2d3a0 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
2d3b0 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
2d3c0 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
2d3d0 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
2d3e0 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
2d3f0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
2d400 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
2d410 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2d420 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2d430 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
2d440 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
2d450 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
2d460 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
2d470 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d480 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
2d490 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
2d4a0 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
2d4b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2d4c0 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
2d4d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d4e0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2d4f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2d500 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 47 49  s true for [BEGI
2d510 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47  N] since.** [BEG
2d520 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 73 20  IN] merely sets 
2d530 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20  internal flags, 
2d540 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e 7c 42  but the [BEGIN|B
2d550 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20  EGIN IMMEDIATE] 
2d560 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45  and.** [BEGIN|BE
2d570 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d 20 63  GIN EXCLUSIVE] c
2d580 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63 68  ommands do touch
2d590 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
2d5a0 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d so.** sqlite3_
2d5b0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2d5c0 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 66 6f  returns false fo
2d5d0 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73  r those commands
2d5e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2d5f0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73  _stmt_readonly(s
2d600 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2d610 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2d620 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
2d630 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  If A Prepared St
2d640 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e  atement Has Been
2d650 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44   Reset.** METHOD
2d660 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2d670 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d680 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
2d690 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d6a0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
2d6b0 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
2d6c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d6d0 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
2d6e0 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
2d6f0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2d700 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
2d710 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e   has neither run
2d720 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28   to completion (
2d730 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
2d740 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b  ITE_DONE] from [
2d750 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2d760 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65  ) nor.** been re
2d770 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  set using [sqlit
2d780 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e  e3_reset(S)].  ^
2d790 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2d7a0 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65  _busy(S).** inte
2d7b0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61  rface returns fa
2d7c0 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55  lse if S is a NU
2d7d0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
2d7e0 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e  S is not a .** N
2d7f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ULL pointer and 
2d800 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
2d810 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65   to a valid [pre
2d820 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d830 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e  .** object, then
2d840 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2d850 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
2d860 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
2d870 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ble..**.** This 
2d880 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2d890 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61   used in combina
2d8a0 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65  tion [sqlite3_ne
2d8b0 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f  xt_stmt()].** to
2d8c0 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70   locate all prep
2d8d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
2d8e0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2d8f0 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63  a database .** c
2d900 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61  onnection that a
2d910 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65  re in need of be
2d920 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73  ing reset.  This
2d930 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a   can be used,.**
2d940 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   for example, in
2d950 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74   diagnostic rout
2d960 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66  ines to search f
2d970 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20  or prepared .** 
2d980 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
2d990 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72  are holding a tr
2d9a0 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a  ansaction open..
2d9b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
2d9c0 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
2d9d0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2d9e0 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
2d9f0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
2da00 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
2da10 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
2da20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
2da30 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
2da40 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
2da50 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2da60 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2da70 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
2da80 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
2da90 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
2daa0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
2dab0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
2dac0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
2dad0 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
2dae0 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
2daf0 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
2db00 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
2db10 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
2db20 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
2db30 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2db40 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
2db50 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
2db60 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
2db70 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
2db80 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
2db90 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
2dba0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
2dbb0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2dbc0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
2dbd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2dbe0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
2dbf0 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
2dc00 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
2dc10 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
2dc20 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2dc30 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
2dc40 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
2dc50 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
2dc60 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
2dc70 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
2dc80 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
2dc90 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
2dca0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2dcb0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
2dcc0 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74  value_dup()] int
2dcd0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2dce0 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20  ed to construct 
2dcf0 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63  a new .** protec
2dd00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2dd10 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74  e from an unprot
2dd20 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2dd30 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
2dd40 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
2dd50 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
2dd60 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
2dd70 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
2dd80 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
2dd90 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
2dda0 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
2ddb0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2ddc0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2ddd0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
2dde0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
2ddf0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2de00 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2de10 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
2de20 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
2de30 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
2de40 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
2de50 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
2de60 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
2de70 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
2de80 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
2de90 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
2dea0 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
2deb0 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
2dec0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
2ded0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2dee0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
2def0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
2df00 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
2df10 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
2df20 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2df30 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2df40 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2df50 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
2df60 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
2df70 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
2df80 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
2df90 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
2dfa0 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
2dfb0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
2dfc0 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
2dfd0 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
2dfe0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
2dff0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2e000 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2e010 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2e020 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
2e030 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
2e040 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2e050 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2e060 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
2e070 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
2e080 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
2e090 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
2e0a0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
2e0b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2e0c0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
2e0d0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
2e0e0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2e0f0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2e100 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2e110 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2e120 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
2e130 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
2e140 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e150 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
2e160 75 73 65 64 20 61 73 20 61 72 67 75 6d 65 6e 74  used as argument
2e170 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
2e180 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2e190 2c 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  , [sqlite3_bind_
2e1a0 76 61 6c 75 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  value()], and.**
2e1b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2e1c0 64 75 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  dup()]..** The [
2e1d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2e1e0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
2e1f0 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
2e200 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
2e210 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
2e220 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e230 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
2e240 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2e250 6c 69 74 65 33 5f 76 61 6c 75 65 20 73 71 6c 69  lite3_value sqli
2e260 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
2e270 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
2e280 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2e290 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
2e2a0 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
2e2b0 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
2e2c0 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
2e2d0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
2e2e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2e2f0 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
2e300 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
2e310 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
2e320 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
2e330 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
2e340 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2e350 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2e360 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
2e370 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e380 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2e390 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
2e3a0 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
2e3b0 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
2e3c0 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
2e3d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
2e3e0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
2e3f0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2e400 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2e410 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
2e420 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
2e430 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2e440 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
2e450 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
2e460 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
2e470 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
2e480 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
2e490 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2e4a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
2e4b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
2e4c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e4d0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
2e4e0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
2e4f0 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
2e500 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
2e510 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
2e520 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
2e530 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
2e540 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
2e550 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
2e560 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
2e570 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
2e580 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2e590 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  _stmt.**.** ^(In
2e5a0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2e5b0 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
2e5c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e5d0 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
2e5e0 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
2e5f0 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
2e600 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
2e610 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
2e620 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
2e630 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
2e640 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2e650 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
2e660 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
2e670 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
2e680 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
2e690 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2e6a0 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
2e6b0 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
2e6c0 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
2e6d0 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
2e6e0 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
2e6f0 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
2e700 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
2e710 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
2e720 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
2e730 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
2e740 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
2e750 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
2e760 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
2e770 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
2e780 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2e790 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
2e7a0 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
2e7b0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2e7c0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
2e7d0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2e7e0 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
2e7f0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
2e800 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2e810 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
2e820 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
2e830 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2e840 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
2e850 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
2e860 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2e870 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2e880 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
2e890 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
2e8a0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
2e8b0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2e8c0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
2e8d0 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
2e8e0 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
2e8f0 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
2e900 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
2e910 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2e920 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
2e930 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
2e940 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
2e950 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
2e960 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
2e970 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2e980 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
2e990 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
2e9a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2e9b0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2e9c0 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
2e9d0 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
2e9e0 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
2e9f0 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
2ea00 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
2ea10 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
2ea20 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
2ea30 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
2ea40 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
2ea50 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
2ea60 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2ea70 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
2ea80 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
2ea90 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
2eaa0 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
2eab0 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
2eac0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
2ead0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2eae0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2eaf0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2eb00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2eb10 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
2eb20 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2eb30 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2eb40 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
2eb50 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
2eb60 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
2eb70 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
2eb80 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
2eb90 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
2eba0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
2ebb0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
2ebc0 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
2ebd0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
2ebe0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2ebf0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2ec00 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
2ec10 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
2ec20 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2ec30 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
2ec40 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
2ec50 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
2ec60 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2ec70 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
2ec80 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2ec90 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2eca0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2ecb0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2ecc0 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
2ecd0 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
2ece0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
2ecf0 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
2ed00 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
2ed10 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
2ed20 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
2ed30 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2ed40 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2ed50 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2ed60 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
2ed70 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
2ed80 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2ed90 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
2eda0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2edb0 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
2edc0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2edd0 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
2ede0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2edf0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2ee00 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a  d_text64() then.
2ee10 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  ** that paramete
2ee20 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
2ee30 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
2ee40 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
2ee50 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
2ee60 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
2ee70 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
2ee80 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
2ee90 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
2eea0 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
2eeb0 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
2eec0 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
2eed0 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
2eee0 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
2eef0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
2ef00 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
2ef10 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
2ef20 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
2ef30 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
2ef40 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
2ef50 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
2ef60 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
2ef70 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2ef80 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
2ef90 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42  ment to the BLOB
2efa0 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64   and string bind
2efb0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ing interfaces.*
2efc0 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  * is a destructo
2efd0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
2efe0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2eff0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
2f000 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
2f010 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
2f020 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2f030 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
2f040 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2f050 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
2f060 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
2f070 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e   bind API fails.
2f080 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2f090 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
2f0a0 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
2f0b0 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
2f0c0 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
2f0d0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
2f0e0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
2f0f0 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
2f100 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
2f110 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
2f120 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
2f130 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2f140 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
2f150 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
2f160 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
2f170 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
2f180 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2f190 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
2f1a0 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
2f1b0 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
2f1c0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2f1d0 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
2f1e0 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67  * ^The sixth arg
2f1f0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2f200 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d  _bind_text64() m
2f210 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a  ust be one of.**
2f220 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2f230 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
2f240 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2f250 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2f260 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63  16LE].** to spec
2f270 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ify the encoding
2f280 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20   of the text in 
2f290 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2f2a0 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ter.  If.** the 
2f2b0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2f2c0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2f2d0 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f  ext64() is not o
2f2e0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c  ne of the.** all
2f2f0 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77  owed values show
2f300 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74  n above, or if t
2f310 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
2f320 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a   is different.**
2f330 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69   from the encodi
2f340 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ng specified by 
2f350 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65  the sixth parame
2f360 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ter, then the be
2f370 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
2f380 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2f390 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2f3a0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
2f3b0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
2f3c0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
2f3d0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
2f3e0 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
2f3f0 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
2f400 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
2f410 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
2f420 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
2f430 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
2f440 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
2f450 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
2f460 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
2f470 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
2f480 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2f490 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
2f4a0 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
2f4b0 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
2f4c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
2f4d0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
2f4e0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
2f4f0 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
2f500 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
2f510 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
2f520 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
2f530 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
2f540 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2f550 6e 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50  nd_pointer(S,I,P
2f560 2c 54 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 61  ,T,D) routine ca
2f570 75 73 65 73 20 74 68 65 20 49 2d 74 68 20 70 61  uses the I-th pa
2f580 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70  rameter in.** [p
2f590 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f5a0 74 5d 20 53 20 74 6f 20 68 61 76 65 20 61 6e 20  t] S to have an 
2f5b0 53 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c  SQL value of NUL
2f5c0 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f 20 62  L, but to also b
2f5d0 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  e.** associated 
2f5e0 77 69 74 68 20 74 68 65 20 70 6f 69 6e 74 65 72  with the pointer
2f5f0 20 50 20 6f 66 20 74 79 70 65 20 54 2e 20 20 5e   P of type T.  ^
2f600 44 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  D is either a NU
2f610 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a  LL pointer or.**
2f620 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2f630 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
2f640 69 6f 6e 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69  ion for P. ^SQLi
2f650 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
2f660 68 65 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72  he.** destructor
2f670 20 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65   D with a single
2f680 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 50 20 77   argument of P w
2f690 68 65 6e 20 69 74 20 69 73 20 66 69 6e 69 73 68  hen it is finish
2f6a0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20  ed using.** P.  
2f6b0 54 68 65 20 54 20 70 61 72 61 6d 65 74 65 72 20  The T parameter 
2f6c0 73 68 6f 75 6c 64 20 62 65 20 61 20 73 74 61 74  should be a stat
2f6d0 69 63 20 73 74 72 69 6e 67 2c 20 70 72 65 66 65  ic string, prefe
2f6e0 72 61 62 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a  rably a string.*
2f6f0 2a 20 6c 69 74 65 72 61 6c 2e 20 54 68 65 20 73  * literal. The s
2f700 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e  qlite3_bind_poin
2f710 74 65 72 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ter() routine is
2f720 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
2f730 5b 70 6f 69 6e 74 65 72 20 70 61 73 73 69 6e 67  [pointer passing
2f740 20 69 6e 74 65 72 66 61 63 65 5d 20 61 64 64 65   interface] adde
2f750 64 20 66 6f 72 20 53 51 4c 69 74 65 20 33 2e 32  d for SQLite 3.2
2f760 30 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  0.0..**.** ^If a
2f770 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
2f780 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2f790 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
2f7a0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
2f7b0 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
2f7c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f7d0 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
2f7e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2f7f0 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
2f800 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2f810 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
2f820 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
2f830 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f840 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
2f850 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
2f860 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2f870 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
2f880 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
2f890 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
2f8a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f8b0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
2f8c0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
2f8d0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
2f8e0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2f8f0 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
2f900 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
2f910 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
2f920 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
2f930 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
2f940 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
2f950 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
2f960 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
2f970 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2f980 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
2f990 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
2f9a0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
2f9b0 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
2f9c0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
2f9d0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
2f9e0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f  .** ^[SQLITE_TOO
2f9f0 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65  BIG] might be re
2fa00 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69  turned if the si
2fa10 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f  ze of a string o
2fa20 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64  r BLOB.** exceed
2fa30 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64  s limits imposed
2fa40 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
2fa50 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
2fa60 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a  T_LENGTH]) or.**
2fa70 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e   [SQLITE_MAX_LEN
2fa80 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  GTH]..** ^[SQLIT
2fa90 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
2faa0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
2fab0 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
2fac0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
2fad0 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
2fae0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2faf0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
2fb00 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2fb10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2fb20 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2fb30 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2fb40 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2fb50 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
2fb60 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2fb70 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
2fb80 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2fb90 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
2fba0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2fbb0 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
2fbc0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2fbd0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
2fbe0 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
2fbf0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2fc00 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
2fc10 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
2fc20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2fc30 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2fc40 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2fc50 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2fc60 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
2fc70 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
2fc80 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
2fc90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2fca0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
2fcb0 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
2fcc0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
2fcd0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
2fce0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2fcf0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
2fd00 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
2fd10 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2fd20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2fd30 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e  t,const char*,in
2fd40 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
2fd50 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2fd60 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
2fd70 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2fd80 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2fd90 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2fda0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2fdb0 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65  nd_text64(sqlite
2fdc0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2fdd0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
2fde0 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2fdf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fe00 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
2fe10 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61  *), unsigned cha
2fe20 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74  r encoding);.int
2fe30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
2fe40 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2fe50 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
2fe60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2fe70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2fe80 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65 33 5f  pointer(sqlite3_
2fe90 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  stmt*, int, void
2fea0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 76  *, const char*,v
2feb0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2fec0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2fed0 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
2fee0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2fef0 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t n);.int sqlite
2ff00 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36  3_bind_zeroblob6
2ff10 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2ff20 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69   int, sqlite3_ui
2ff30 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
2ff40 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2ff50 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
2ff60 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2ff70 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2ff80 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
2ff90 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
2ffa0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
2ffb0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
2ffc0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
2ffd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
2ffe0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
2fff0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
30000 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
30010 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
30020 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
30030 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
30040 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
30050 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
30060 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
30070 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
30080 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
30090 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
300a0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
300b0 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
300c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
300d0 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
300e0 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
300f0 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
30100 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
30110 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
30120 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
30130 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
30140 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
30150 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
30160 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
30170 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
30180 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
30190 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
301a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
301b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
301c0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
301d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
301e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
301f0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
30200 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
30210 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
30220 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
30230 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30240 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
30250 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
30260 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
30270 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
30280 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
30290 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
302a0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
302b0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
302c0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
302d0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
302e0 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
302f0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
30300 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
30310 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
30320 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
30330 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
30340 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
30350 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
30360 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
30370 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
30380 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
30390 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
303a0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
303b0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
303c0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
303d0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
303e0 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
303f0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
30400 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
30410 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
30420 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
30430 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
30440 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
30450 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
30460 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
30470 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
30480 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
30490 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
304a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
304b0 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
304c0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
304d0 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
304e0 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
304f0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
30500 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
30510 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
30520 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
30530 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
30540 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
30550 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
30560 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
30570 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
30580 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
30590 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
305a0 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
305b0 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
305c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
305d0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
305e0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f  epare16_v2()], o
305f0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
30600 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v3()]..**.*
30610 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
30620 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
30630 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
30640 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
30650 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
30660 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
30670 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30680 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
30690 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
306a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
306b0 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
306c0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
306d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
306e0 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
306f0 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
30700 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Name.** METHOD:
30710 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30720 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
30730 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
30740 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
30750 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
30760 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
30770 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
30780 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
30790 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
307a0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
307b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
307c0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
307d0 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
307e0 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
307f0 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
30800 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
30810 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
30820 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
30830 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
30840 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
30850 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
30860 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
30870 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
30880 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30890 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
308a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
308b0 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v3()]..**.** See
308c0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
308d0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
308e0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
308f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30900 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
30910 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
30920 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
30930 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ame()]..*/.int s
30940 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30950 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
30960 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
30970 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
30980 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30990 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
309a0 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
309b0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45   Statement.** ME
309c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
309d0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  mt.**.** ^Contra
309e0 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
309f0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
30a00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
30a10 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
30a20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
30a30 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
30a40 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
30a50 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
30a60 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
30a70 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
30a80 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
30a90 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
30aa0 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
30ab0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
30ac0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
30ad0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
30ae0 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
30af0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
30b00 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
30b10 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
30b20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
30b30 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
30b40 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
30b50 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
30b60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30b70 2e 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69  . ^If this routi
30b80 6e 65 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ne returns 0, th
30b90 61 74 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a  at means the .**
30ba0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30bb0 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f  ment] returns no
30bc0 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
30bd0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
30be0 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75  .** ^However, ju
30bf0 73 74 20 62 65 63 61 75 73 65 20 74 68 69 73 20  st because this 
30c00 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
30c10 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65  a positive numbe
30c20 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65  r does not.** me
30c30 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d  an that one or m
30c40 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61  ore rows of data
30c50 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65   will be returne
30c60 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74  d.  ^A SELECT st
30c70 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20  atement.** will 
30c80 61 6c 77 61 79 73 20 68 61 76 65 20 61 20 70 6f  always have a po
30c90 73 69 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63  sitive sqlite3_c
30ca0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75  olumn_count() bu
30cb0 74 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  t depending on t
30cc0 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  he.** WHERE clau
30cd0 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61  se constraints a
30ce0 6e 64 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e  nd the table con
30cf0 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72  tent, it might r
30d00 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a  eturn no rows..*
30d10 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
30d20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
30d30 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
30d40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
30d50 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
30d60 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
30d70 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
30d80 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
30d90 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
30da0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30db0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
30dc0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
30dd0 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
30de0 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
30df0 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
30e00 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
30e10 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
30e20 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
30e30 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
30e40 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30e50 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
30e60 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
30e70 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
30e80 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
30e90 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
30ea0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
30eb0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
30ec0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
30ed0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
30ee0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
30ef0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
30f00 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
30f10 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
30f20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
30f30 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
30f40 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
30f50 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
30f60 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
30f70 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
30f80 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
30f90 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
30fa0 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
30fb0 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
30fc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
30fd0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
30fe0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
30ff0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
31000 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
31010 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
31020 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
31030 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
31040 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
31050 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
31060 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
31070 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
31080 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
31090 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
310a0 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
310b0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
310c0 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
310d0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
310e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
310f0 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
31100 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
31110 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
31120 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
31130 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
31140 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
31150 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
31160 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
31170 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
31180 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
31190 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
311a0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
311b0 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
311c0 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
311d0 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
311e0 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
311f0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
31200 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
31210 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
31220 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
31230 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
31240 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
31250 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
31260 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
31270 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
31280 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
31290 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
312a0 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
312b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
312c0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
312d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
312e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
312f0 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
31300 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
31310 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
31320 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
31330 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
31340 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
31350 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
31360 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
31370 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
31380 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
31390 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
313a0 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
313b0 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
313c0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
313d0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
313e0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
313f0 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
31400 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
31410 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
31420 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
31430 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
31440 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
31450 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
31460 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
31470 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
31480 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
31490 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
314a0 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
314b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
314c0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
314d0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
314e0 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
314f0 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
31500 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31510 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
31520 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
31530 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
31540 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
31550 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
31560 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
31570 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
31580 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
31590 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
315a0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
315b0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
315c0 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
315d0 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
315e0 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
315f0 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
31600 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
31610 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
31620 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
31630 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
31640 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
31650 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
31660 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
31670 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
31680 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
31690 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
316a0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
316b0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
316c0 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
316d0 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
316e0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
316f0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
31700 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
31710 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
31720 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
31730 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
31740 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
31750 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
31760 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
31770 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
31780 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
31790 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
317a0 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
317b0 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
317c0 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
317d0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
317e0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
317f0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
31800 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
31810 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
31820 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
31830 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
31840 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
31850 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
31860 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
31870 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
31880 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
31890 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
318a0 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
318b0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
318c0 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
318d0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
318e0 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
318f0 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
31900 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
31910 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
31920 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
31930 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
31940 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
31950 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
31960 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
31970 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
31980 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
31990 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
319a0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
319b0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
319c0 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
319d0 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
319e0 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
319f0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
31a00 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
31a10 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
31a20 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
31a30 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
31a40 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
31a50 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
31a60 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
31a70 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
31a80 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
31a90 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
31aa0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
31ab0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
31ac0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
31ad0 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
31ae0 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
31af0 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
31b00 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
31b10 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
31b20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
31b30 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
31b40 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
31b50 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
31b60 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
31b70 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
31b80 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
31b90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
31ba0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
31bb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
31bc0 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
31bd0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
31be0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
31bf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
31c00 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
31c10 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
31c20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
31c30 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
31c40 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
31c50 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
31c60 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
31c70 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
31c80 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
31c90 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
31ca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
31cb0 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
31cc0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
31cd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31ce0 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
31cf0 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
31d00 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
31d10 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
31d20 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
31d30 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
31d40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31d50 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
31d60 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
31d70 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
31d80 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
31d90 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
31da0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
31db0 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
31dc0 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
31dd0 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
31de0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
31df0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
31e00 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
31e10 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
31e20 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
31e30 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
31e40 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
31e50 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
31e60 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
31e70 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
31e80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
31e90 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
31ea0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
31eb0 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
31ec0 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
31ed0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
31ee0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
31ef0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
31f00 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
31f10 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
31f20 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
31f30 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
31f40 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
31f50 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
31f60 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
31f70 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
31f80 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
31f90 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
31fa0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
31fb0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
31fc0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
31fd0 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
31fe0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
31ff0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
32000 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
32010 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
32020 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
32030 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
32040 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
32050 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
32060 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
32070 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
32080 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
32090 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
320a0 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
320b0 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
320c0 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
320d0 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
320e0 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
320f0 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
32100 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
32110 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
32120 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
32130 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
32140 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
32150 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
32160 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
32170 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
32180 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
32190 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
321a0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
321b0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
321c0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
321d0 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
321e0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
321f0 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
32200 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
32210 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
32220 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
32230 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
32240 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
32250 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
32260 20 75 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a   using any of.**
32270 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32280 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
32290 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c  3_prepare_v3()],
322a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
322b0 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72  e16_v2()],.** or
322c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
322d0 65 31 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65  e16_v3()] or one
322e0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
322f0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
32300 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
32310 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
32320 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
32330 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
32340 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
32350 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
32360 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
32370 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
32380 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
32390 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
323a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
323b0 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
323c0 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
323d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
323e0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
323f0 74 68 65 20 6e 65 77 65 72 20 22 76 58 22 20 69  the newer "vX" i
32400 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71  nterfaces.** [sq
32410 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
32420 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72  ()], [sqlite3_pr
32430 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
32440 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
32450 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v3()],.** [sqlit
32460 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
32470 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
32480 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
32490 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
324a0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
324b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
324c0 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
324d0 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20  the.** new "vX" 
324e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
324f0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
32500 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
32510 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
32520 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
32530 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
32540 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
32550 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
32560 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
32570 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
32580 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
32590 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
325a0 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
325b0 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
325c0 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
325d0 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
325e0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
325f0 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
32600 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
32610 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
32620 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
32630 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
32640 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
32650 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
32660 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
32670 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
32680 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
32690 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
326a0 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
326b0 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
326c0 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
326d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
326e0 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
326f0 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
32700 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
32710 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
32720 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
32730 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
32740 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
32750 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
32760 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
32770 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70  within an.** exp
32780 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
32790 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
327a0 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
327b0 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
327c0 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
327d0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
327e0 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
327f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
32800 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
32810 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
32820 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
32830 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
32840 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
32850 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
32860 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
32870 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
32880 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
32890 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
328a0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
328b0 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
328c0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
328d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
328e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
328f0 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
32900 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
32910 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
32920 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
32930 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
32940 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
32950 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
32960 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
32970 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
32980 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
32990 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
329a0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
329b0 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
329c0 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
329d0 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
329e0 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
329f0 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
32a00 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
32a10 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
32a20 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
32a30 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
32a40 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
32a50 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
32a60 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
32a70 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
32a80 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
32a90 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
32aa0 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
32ab0 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
32ac0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
32ad0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
32ae0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
32af0 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
32b00 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
32b10 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
32b20 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
32b30 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
32b40 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
32b50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
32b60 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
32b70 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
32b80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32b90 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
32ba0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
32bb0 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
32bc0 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
32bd0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
32be0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
32bf0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
32c00 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
32c10 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
32c20 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
32c30 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
32c40 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
32c50 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
32c60 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
32c70 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
32c80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32c90 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
32ca0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
32cb0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
32cc0 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
32cd0 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
32ce0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
32cf0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
32d00 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
32d10 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
32d20 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
32d30 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
32d40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
32d50 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
32d60 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
32d70 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
32d80 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
32d90 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
32da0 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
32db0 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
32dc0 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
32dd0 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
32de0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
32df0 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
32e00 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
32e10 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
32e20 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
32e30 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
32e40 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
32e50 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
32e60 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
32e70 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
32e80 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
32e90 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
32ea0 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
32eb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32ec0 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
32ed0 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
32ee0 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
32ef0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
32f00 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b  ().  But after [
32f10 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
32f20 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32  ] ([dateof:3.6.2
32f30 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  3.1],.** sqlite3
32f40 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
32f50 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
32f60 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
32f70 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
32f80 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
32f90 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
32fa0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
32fb0 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
32fc0 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
32fd0 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
32fe0 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
32ff0 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
33000 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
33010 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
33020 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
33030 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
33040 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
33050 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
33060 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
33070 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
33080 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
33090 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
330a0 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
330b0 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
330c0 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
330d0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
330e0 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
330f0 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
33100 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
33110 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
33120 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
33130 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
33140 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
33150 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
33160 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
33170 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
33180 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
33190 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
331a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
331b0 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
331c0 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
331d0 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
331e0 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
331f0 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
33200 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
33210 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
33220 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
33230 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
33240 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
33250 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
33260 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
33270 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
33280 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
33290 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
332a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
332b0 5f 76 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v3()] or [sqlit
332c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
332d0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
332e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
332f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
33300 61 72 65 31 36 5f 76 33 28 29 5d 20 69 6e 73 74  are16_v3()] inst
33310 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
33320 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
33330 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
33340 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
33350 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
33360 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
33370 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
33380 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
33390 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
333a0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
333b0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
333c0 68 65 20 22 76 58 22 20 69 6e 74 65 72 66 61 63  he "vX" interfac
333d0 65 73 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  es is recommende
333e0 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
333f0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
33400 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
33410 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
33420 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
33430 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54  esult set.** MET
33440 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
33450 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
33460 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
33470 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
33480 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
33490 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
334a0 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77  e.** current row
334b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
334c0 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
334d0 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
334e0 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74   ^If prepared st
334f0 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e  atement P does n
33500 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20  ot have results 
33510 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a  ready to return.
33520 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f  ** (via calls to
33530 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
33540 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74  lumn_int | sqlit
33550 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f  e3_column_*()] o
33560 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29  f.** interfaces)
33570 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61   then sqlite3_da
33580 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75  ta_count(P) retu
33590 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73  rns 0..** ^The s
335a0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
335b0 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73  t(P) routine als
335c0 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50  o returns 0 if P
335d0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
335e0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  er..** ^The sqli
335f0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
33600 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
33610 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69  s 0 if the previ
33620 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ous call to.** [
33630 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
33640 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
33650 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73  E_DONE].  ^The s
33660 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
33670 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  t(P).** will ret
33680 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20  urn non-zero if 
33690 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
336a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
336b0 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  P) returned.** [
336c0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63  SQLITE_ROW], exc
336d0 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20  ept in the case 
336e0 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69  of the [PRAGMA i
336f0 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75  ncremental_vacuu
33700 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61  m].** where it a
33710 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65  lways returns ze
33720 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74  ro since each st
33730 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69  ep of that multi
33740 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20  -step.** pragma 
33750 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e  returns 0 column
33760 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  s of data..**.**
33770 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
33780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
33790 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
337a0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
337b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
337c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
337d0 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
337e0 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
337f0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
33800 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
33810 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
33820 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
33830 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
33840 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
33850 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
33860 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
33870 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
33880 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
33890 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
338a0 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
338b0 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
338c0 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
338d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
338e0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
338f0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
33900 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
33910 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
33920 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
33930 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
33940 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
33950 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
33960 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
33970 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
33980 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
33990 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
339a0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
339b0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
339c0 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
339d0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
339e0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
339f0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
33a00 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
33a10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
33a20 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
33a30 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
33a40 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
33a50 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
33a60 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
33a70 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
33a80 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
33a90 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
33aa0 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
33ab0 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
33ac0 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
33ad0 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
33ae0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
33af0 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
33b00 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
33b10 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45  functions}.** ME
33b20 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
33b30 6d 74 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d  mt.**.** <b>Summ
33b40 61 72 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f  ary:</b>.** <blo
33b50 63 6b 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62  ckquote><table b
33b60 6f 72 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 64  order=0 cellpadd
33b70 69 6e 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e  ing=0 cellspacin
33b80 67 3d 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  g=0>.** <tr><td>
33b90 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
33ba0 6e 5f 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72  n_blob</b><td>&r
33bb0 61 72 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73  arr;<td>BLOB res
33bc0 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
33bd0 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
33be0 5f 64 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26  _double</b><td>&
33bf0 72 61 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65  rarr;<td>REAL re
33c00 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
33c10 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
33c20 6e 5f 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61  n_int</b><td>&ra
33c30 72 72 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e  rr;<td>32-bit IN
33c40 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20  TEGER result.** 
33c50 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
33c60 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c  e3_column_int64<
33c70 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
33c80 3e 36 34 2d 62 69 74 20 49 4e 54 45 47 45 52 20  >64-bit INTEGER 
33c90 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74  result.** <tr><t
33ca0 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c  d><b>sqlite3_col
33cb0 75 6d 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e  umn_text</b><td>
33cc0 26 72 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20  &rarr;<td>UTF-8 
33cd0 54 45 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c  TEXT result.** <
33ce0 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
33cf0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c  3_column_text16<
33d00 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
33d10 3e 55 54 46 2d 31 36 20 54 45 58 54 20 72 65 73  >UTF-16 TEXT res
33d20 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c  ult.** <tr><td><
33d30 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  b>sqlite3_column
33d40 5f 76 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72  _value</b><td>&r
33d50 61 72 72 3b 3c 74 64 3e 54 68 65 20 72 65 73 75  arr;<td>The resu
33d60 6c 74 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71  lt as an .** [sq
33d70 6c 69 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72  lite3_value|unpr
33d80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
33d90 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  value] object..*
33da0 2a 20 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b  * <tr><td>&nbsp;
33db0 3c 74 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e  <td>&nbsp;<td>&n
33dc0 62 73 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  bsp;.** <tr><td>
33dd0 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
33de0 6e 5f 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26  n_bytes</b><td>&
33df0 72 61 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66  rarr;<td>Size of
33e00 20 61 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20   a BLOB.** or a 
33e10 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c  UTF-8 TEXT resul
33e20 74 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74  t in bytes.** <t
33e30 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
33e40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26  _column_bytes16&
33e50 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a  nbsp;&nbsp;</b>.
33e60 2a 2a 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62  ** <td>&rarr;&nb
33e70 73 70 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a  sp;&nbsp;<td>Siz
33e80 65 20 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54  e of UTF-16.** T
33e90 45 58 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20  EXT in bytes.** 
33ea0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
33eb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f  e3_column_type</
33ec0 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
33ed0 44 65 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74  Default.** datat
33ee0 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ype of the resul
33ef0 74 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62  t.** </table></b
33f00 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
33f10 20 3c 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e   <b>Details:</b>
33f20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
33f30 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
33f40 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
33f50 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
33f60 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
33f70 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
33f80 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
33f90 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
33fa0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
33fb0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
33fc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
33fd0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
33fe0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
33ff0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
34000 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
34010 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
34020 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
34030 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
34040 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
34050 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
34060 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
34070 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
34080 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
34090 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
340a0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
340b0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
340c0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
340d0 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
340e0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
340f0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
34100 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
34110 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
34120 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
34130 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
34140 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
34150 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
34160 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
34170 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
34180 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
34190 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
341a0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
341b0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
341c0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
341d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
341e0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
341f0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
34200 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
34210 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
34220 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
34230 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
34240 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
34250 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
34260 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
34270 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
34280 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
34290 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
342a0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
342b0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
342c0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
342d0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
342e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
342f0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
34300 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
34310 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
34320 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
34330 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
34340 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
34350 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
34360 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
34370 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
34380 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
34390 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
343a0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
343b0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
343c0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
343d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
343e0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
343f0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
34400 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
34410 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 73  *.** The first s
34420 69 78 20 69 6e 74 65 72 66 61 63 65 73 20 28 5f  ix interfaces (_
34430 62 6c 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f  blob, _double, _
34440 69 6e 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65  int, _int64, _te
34450 78 74 2c 20 61 6e 64 20 5f 74 65 78 74 31 36 29  xt, and _text16)
34460 0a 2a 2a 20 65 61 63 68 20 72 65 74 75 72 6e 20  .** each return 
34470 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61 20 72  the value of a r
34480 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20  esult column in 
34490 61 20 73 70 65 63 69 66 69 63 20 64 61 74 61 20  a specific data 
344a0 66 6f 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74  format.  If.** t
344b0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
344c0 20 69 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c   is not initiall
344d0 79 20 69 6e 20 74 68 65 20 72 65 71 75 65 73 74  y in the request
344e0 65 64 20 66 6f 72 6d 61 74 20 28 66 6f 72 20 65  ed format (for e
344f0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68  xample,.** if th
34500 65 20 71 75 65 72 79 20 72 65 74 75 72 6e 73 20  e query returns 
34510 61 6e 20 69 6e 74 65 67 65 72 20 62 75 74 20 74  an integer but t
34520 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
34530 6e 5f 74 65 78 74 28 29 20 69 6e 74 65 72 66 61  n_text() interfa
34540 63 65 0a 2a 2a 20 69 73 20 75 73 65 64 20 74 6f  ce.** is used to
34550 20 65 78 74 72 61 63 74 20 74 68 65 20 76 61 6c   extract the val
34560 75 65 29 20 74 68 65 6e 20 61 6e 20 61 75 74 6f  ue) then an auto
34570 6d 61 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65  matic type conve
34580 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
34590 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
345a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
345b0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
345c0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
345d0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
345e0 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
345f0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
34600 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
34610 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
34620 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
34630 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
34640 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
34650 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
34660 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
34670 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
34680 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
34690 4c 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  L]..** The retur
346a0 6e 20 76 61 6c 75 65 20 6f 66 20 73 71 6c 69 74  n value of sqlit
346b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
346c0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
346d0 64 65 63 69 64 65 20 77 68 69 63 68 0a 2a 2a 20  decide which.** 
346e0 6f 66 20 74 68 65 20 66 69 72 73 74 20 73 69 78  of the first six
346f0 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c   interface shoul
34700 64 20 62 65 20 75 73 65 64 20 74 6f 20 65 78 74  d be used to ext
34710 72 61 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20  ract the column 
34720 76 61 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61  value..** The va
34730 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
34740 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34750 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
34760 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a  aningful if no.*
34770 2a 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65  * automatic type
34780 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
34790 65 20 6f 63 63 75 72 72 65 64 20 66 6f 72 20 74  e occurred for t
347a0 68 65 20 76 61 6c 75 65 20 69 6e 20 71 75 65 73  he value in ques
347b0 74 69 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72  tion.  .** After
347c0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
347d0 6f 6e 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f  on, the result o
347e0 66 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  f calling sqlite
347f0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
34800 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2c  ** is undefined,
34810 20 74 68 6f 75 67 68 20 68 61 72 6d 6c 65 73 73   though harmless
34820 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
34830 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
34840 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
34850 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
34860 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
34870 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
34880 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
34890 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  .**.** If the re
348a0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
348b0 72 20 61 20 54 45 58 54 20 73 74 72 69 6e 67 2c  r a TEXT string,
348c0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
348d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
348e0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  .** or sqlite3_c
348f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
34900 69 6e 74 65 72 66 61 63 65 73 20 63 61 6e 20 62  interfaces can b
34910 65 20 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d  e used to determ
34920 69 6e 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20  ine the size.** 
34930 6f 66 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  of that BLOB or 
34940 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^I
34950 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
34960 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
34970 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
34980 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34990 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
349a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
349b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
349c0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
349d0 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
349e0 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
349f0 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
34a00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34a10 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
34a20 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
34a30 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
34a40 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
34a50 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
34a60 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
34a70 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
34a80 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
34a90 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
34aa0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
34ab0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
34ac0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
34ad0 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
34ae0 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
34af0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
34b00 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
34b10 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
34b20 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
34b30 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
34b40 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
34b50 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
34b60 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
34b70 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
34b80 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
34b90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
34ba0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
34bb0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
34bc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
34bd0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
34be0 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
34bf0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
34c00 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
34c10 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
34c20 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
34c30 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
34c40 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
34c50 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
34c60 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
34c70 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
34c80 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
34c90 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
34ca0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34cb0 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
34cc0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
34cd0 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
34ce0 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
34cf0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
34d00 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
34d10 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
34d20 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
34d30 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
34d40 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
34d50 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
34d60 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
34d70 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
34d80 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
34d90 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
34da0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
34db0 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
34dc0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
34dd0 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
34de0 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
34df0 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
34e00 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
34e10 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
34e20 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
34e30 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
34e40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34e50 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
34e60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34e70 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
34e80 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
34e90 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
34ea0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
34eb0 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
34ec0 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
34ed0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
34ee0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
34ef0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
34f00 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
34f10 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
34f20 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
34f30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
34f40 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
34f50 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
34f60 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
34f70 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
34f80 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
34f90 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
34fa0 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20  <b>Warning:</b> 
34fb0 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
34fc0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
34fd0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
34fe0 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
34ff0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
35000 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49  alue] object.  I
35010 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65  n a multithreade
35020 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a  d environment,.*
35030 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  * an unprotected
35040 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
35050 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62  bject may only b
35060 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69  e used safely wi
35070 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  th.** [sqlite3_b
35080 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ind_value()] and
35090 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
350a0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66  _value()]..** If
350b0 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65   the [unprotecte
350c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
350d0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
350e0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
350f0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
35100 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f  is used in any o
35110 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64  ther way, includ
35120 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  ing calls.** to 
35130 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
35140 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
35150 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
35160 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
35170 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
35180 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20  e_bytes()], the 
35190 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20  behavior is not 
351a0 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48  threadsafe..** H
351b0 65 6e 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  ence, the sqlite
351c0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
351d0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
351e0 20 6e 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75   normally only u
351f0 73 65 66 75 6c 20 77 69 74 68 69 6e 20 74 68 65  seful within the
35200 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35210 6f 66 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74  of .** [applicat
35220 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
35230 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76  functions] or [v
35240 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20  irtual tables], 
35250 6e 6f 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f  not within.** to
35260 70 2d 6c 65 76 65 6c 20 61 70 70 6c 69 63 61 74  p-level applicat
35270 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20  ion code..**.** 
35280 54 68 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  The these routin
35290 65 73 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74  es may attempt t
352a0 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 64 61  o convert the da
352b0 74 61 74 79 70 65 20 6f 66 20 74 68 65 20 72 65  tatype of the re
352c0 73 75 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78  sult..** ^For ex
352d0 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
352e0 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
352f0 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
35300 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
35310 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
35320 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
35330 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
35340 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
35350 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
35360 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
35370 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
35380 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
35390 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
353a0 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
353b0 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
353c0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
353d0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
353e0 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
353f0 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
35400 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
35410 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
35420 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
35430 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
35440 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
35450 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
35460 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
35470 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
35480 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
35490 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
354a0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
354b0 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
354c0 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
354d0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
354e0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
354f0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
35500 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
35510 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
35520 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
35530 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
35540 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
35550 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
35560 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
35570 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
35580 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
35590 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
355a0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
355b0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
355c0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
355d0 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
355e0 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
355f0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
35600 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
35610 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
35620 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
35630 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
35640 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
35650 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
35660 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
35670 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
35680 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
35690 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f  d> [CAST] to BLO
356a0 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  B.** <tr><td>  T
356b0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
356c0 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
356d0 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
356e0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
356f0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
35700 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
35710 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
35720 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
35730 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
35740 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
35750 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
35760 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
35770 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
35780 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
35790 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
357a0 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
357b0 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
357c0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
357d0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
357e0 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
357f0 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
35800 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
35810 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
35820 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  )^.**.** Note th
35830 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
35840 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
35850 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
35860 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
35870 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
35880 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
35890 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
358a0 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
358b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
358c0 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
358d0 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
358e0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
358f0 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
35900 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
35910 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
35920 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
35930 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
35940 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
35950 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
35960 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
35970 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
35980 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
35990 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
359a0 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
359b0 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
359c0 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
359d0 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
359e0 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
359f0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
35a00 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
35a10 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
35a20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35a30 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
35a40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35a50 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
35a60 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
35a70 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
35a80 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
35a90 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
35aa0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
35ab0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
35ac0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
35ad0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
35ae0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
35af0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
35b00 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
35b10 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
35b20 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
35b30 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
35b40 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
35b50 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
35b60 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
35b70 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
35b80 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
35b90 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
35ba0 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
35bb0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
35bc0 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
35bd0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
35be0 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
35bf0 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
35c00 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
35c10 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
35c20 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
35c30 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
35c40 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
35c50 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
35c60 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
35c70 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
35c80 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
35c90 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
35ca0 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
35cb0 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
35cc0 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
35cd0 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20  e safest policy 
35ce0 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
35cf0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
35d00 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
35d10 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
35d20 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
35d30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35d40 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
35d50 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
35d60 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
35d70 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
35d80 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
35d90 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
35da0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
35db0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
35dc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
35dd0 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
35de0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35df0 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
35e00 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
35e10 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
35e20 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
35e30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35e40 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
35e50 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
35e60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35e70 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
35e80 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
35e90 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
35ea0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
35eb0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
35ec0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
35ed0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
35ee0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
35ef0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
35f00 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
35f10 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
35f20 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
35f30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
35f40 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
35f50 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
35f60 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
35f70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
35f80 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
35f90 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
35fa0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
35fb0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
35fc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
35fd0 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
35fe0 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
35ff0 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
36000 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
36010 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
36020 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
36030 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
36040 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
36050 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
36060 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
36070 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
36080 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
36090 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
360a0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
360b0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
360c0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
360d0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e  matically.  Do n
360e0 6f 74 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  ot pass the poin
360f0 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
36100 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
36110 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
36120 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36130 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
36140 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
36150 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
36160 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
36170 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
36180 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
36190 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
361a0 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
361b0 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
361c0 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
361d0 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
361e0 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
361f0 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
36200 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
36210 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
36220 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
36230 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
36240 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
36250 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
36260 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
36270 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
36280 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
36290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
362a0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
362b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f  *, int iCol);.do
362c0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
362d0 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
362e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
362f0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
36300 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
36310 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36320 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  Col);.sqlite3_in
36330 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
36340 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
36350 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36360 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  );.const unsigne
36370 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  d char *sqlite3_
36380 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
36390 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
363a0 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  Col);.const void
363b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
363c0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
363d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
363e0 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
363f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
36400 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
36410 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36420 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
36430 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
36440 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
36450 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
36460 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
36470 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
36480 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
36490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
364a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
364b0 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
364c0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
364d0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
364e0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
364f0 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71  * DESTRUCTOR: sq
36500 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
36510 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
36520 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
36530 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
36540 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
36550 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
36560 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
36570 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
36580 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
36590 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
365a0 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
365b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
365c0 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
365d0 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
365e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
365f0 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
36600 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
36610 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
36620 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
36630 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
36640 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
36650 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
36660 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
36670 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
36680 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
36690 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
366a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
366b0 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
366c0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
366d0 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
366e0 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
366f0 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
36700 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
36710 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
36720 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
36730 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
36740 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
36750 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
36760 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
36770 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
36780 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
36790 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
367a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
367b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
367c0 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
367d0 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
367e0 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
367f0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
36800 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
36810 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
36820 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
36830 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
36840 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
36850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36860 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
36870 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
36880 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
36890 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
368a0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
368b0 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
368c0 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
368d0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
368e0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
368f0 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
36900 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
36910 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
36920 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
36930 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
36940 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
36950 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
36960 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
36970 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
36980 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
36990 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
369a0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
369b0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
369c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
369d0 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
369e0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
369f0 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ct.** METHOD: sq
36a00 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
36a10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
36a20 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
36a30 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
36a40 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
36a50 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
36a60 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
36a70 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
36a80 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
36a90 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
36aa0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
36ab0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
36ac0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
36ad0 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
36ae0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
36af0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
36b00 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
36b10 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
36b20 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
36b30 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
36b40 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
36b50 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
36b60 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
36b70 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
36b80 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
36b90 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36ba0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
36bb0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
36bc0 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
36bd0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
36be0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
36bf0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
36c00 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
36c10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
36c20 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
36c30 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
36c40 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
36c50 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
36c60 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
36c70 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
36c80 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
36c90 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
36ca0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
36cb0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
36cc0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
36cd0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
36ce0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
36cf0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
36d00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
36d10 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
36d20 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
36d30 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
36d40 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
36d50 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
36d60 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
36d70 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
36d80 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
36d90 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
36da0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
36db0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
36dc0 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
36dd0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
36de0 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
36df0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
36e00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
36e10 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
36e20 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
36e30 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
36e40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
36e50 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
36e60 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
36e70 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
36e80 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
36e90 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
36ea0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
36eb0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
36ec0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
36ed0 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ns}.** METHOD: s
36ee0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
36ef0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
36f00 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
36f10 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
36f20 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
36f30 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
36f40 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
36f50 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
36f60 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
36f70 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
36f80 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
36f90 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
36fa0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
36fb0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
36fc0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
36fd0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
36fe0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
36ff0 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
37000 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
37010 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
37020 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
37030 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
37040 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
37050 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
37060 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
37070 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
37080 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
37090 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
370a0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
370b0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
370c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
370d0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
370e0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
370f0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
37100 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
37110 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
37120 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
37130 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
37140 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
37150 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
37160 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
37170 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
37180 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37190 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
371a0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
371b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
371c0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
371d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
371e0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
371f0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
37200 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
37210 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
37220 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
37230 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
37240 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
37250 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
37260 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
37270 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
37280 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
37290 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
372a0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
372b0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
372c0 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
372d0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
372e0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
372f0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
37300 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
37310 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
37320 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
37330 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
37340 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
37350 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
37360 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
37370 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
37380 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
37390 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
373a0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
373b0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
373c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
373d0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
373e0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
373f0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
37400 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
37410 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
37420 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
37430 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
37440 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
37450 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
37460 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
37470 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
37480 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
37490 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
374a0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
374b0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
374c0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
374d0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
374e0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
374f0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
37500 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
37510 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
37520 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
37530 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c  eters.  The appl
37540 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73  ication should s
37550 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  et this paramete
37560 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r to.** [SQLITE_
37570 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20  UTF16LE] if the 
37580 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
37590 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
375a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
375b0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f  ue_text16le()] o
375c0 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b  n an input, or [
375d0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20  SQLITE_UTF16BE] 
375e0 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  if the.** implem
375f0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
37600 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37610 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61  text16be()] on a
37620 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b  n input, or.** [
37630 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66  SQLITE_UTF16] if
37640 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37650 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65  text16()] is use
37660 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  d, or [SQLITE_UT
37670 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  F8].** otherwise
37680 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c  .  ^The same SQL
37690 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
376a0 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
376b0 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67  iple times using
376c0 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72  .** different pr
376d0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
376e0 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66  odings, with dif
376f0 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  ferent implement
37700 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61  ations for.** ea
37710 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20  ch encoding..** 
37720 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
37730 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
37740 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
37750 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
37760 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
37770 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
37780 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
37790 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
377a0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
377b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
377c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61  rth parameter ma
377d0 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20  y optionally be 
377e0 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  ORed with [SQLIT
377f0 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
37800 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68  .** to signal th
37810 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  at the function 
37820 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
37830 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75  rn the same resu
37840 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20  lt given.** the 
37850 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68  same inputs with
37860 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  in a single SQL 
37870 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74  statement.  Most
37880 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
37890 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73  re.** determinis
378a0 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d  tic.  The built-
378b0 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51  in [random()] SQ
378c0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e  L function is an
378d0 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a   example of a.**
378e0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69   function that i
378f0 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73  s not determinis
37900 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65  tic.  The SQLite
37910 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69   query planner i
37920 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72  s able to.** per
37930 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20  form additional 
37940 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e  optimizations on
37950 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66   deterministic f
37960 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65  unctions, so use
37970 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
37980 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
37990 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d  ] flag is recomm
379a0 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73  ended where poss
379b0 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ible..**.** ^(Th
379c0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
379d0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
379e0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
379f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
37a00 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
37a10 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
37a20 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
37a30 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
37a40 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
37a50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
37a60 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65  h, seventh and e
37a70 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73  ighth parameters
37a80 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
37a90 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
37aa0 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
37ab0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
37ac0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
37ad0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
37ae0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
37af0 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
37b00 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
37b10 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
37b20 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
37b30 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
37b40 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
37b50 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  rs must be passe
37b60 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
37b70 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
37b80 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
37b90 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
37ba0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
37bb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
37bc0 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
37bd0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70  Final and NULL p
37be0 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70  ointer must be p
37bf0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
37c00 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
37c10 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
37c20 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
37c30 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
37c40 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c  pointers for all
37c50 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
37c60 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
37c70 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
37c80 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
37c90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
37ca0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
37cb0 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
37cc0 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
37cd0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
37ce0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
37cf0 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
37d00 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
37d10 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
37d20 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
37d30 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
37d40 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
37d50 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
37d60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
37d70 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
37d80 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
37d90 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
37da0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
37db0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
37dc0 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
37dd0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
37de0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
37df0 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
37e00 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
37e10 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
37e20 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
37e30 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
37e40 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
37e50 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
37e60 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
37e70 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
37e80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
37e90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37ea0 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
37eb0 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
37ec0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
37ed0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
37ee0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
37ef0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
37f00 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
37f10 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
37f20 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
37f30 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
37f40 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
37f50 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
37f60 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
37f70 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
37f80 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
37f90 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
37fa0 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
37fb0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
37fc0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
37fd0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
37fe0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
37ff0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
38000 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
38010 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
38020 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
38030 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
38040 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
38050 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
38060 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
38070 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
38080 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
38090 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
380a0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
380b0 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
380c0 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
380d0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
380e0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
380f0 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
38100 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
38110 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
38120 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
38130 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
38140 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
38150 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
38160 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
38170 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
38180 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
38190 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
381a0 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
381b0 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
381c0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
381d0 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
381e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
381f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
38200 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
38210 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
38220 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
38230 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
38240 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
38250 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
38260 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
38270 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
38280 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
38290 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
382a0 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
382b0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
382c0 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
382d0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
382e0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
382f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
38300 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
38310 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
38320 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
38330 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
38340 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
38350 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
38360 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
38370 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
38380 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
38390 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
383a0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
383b0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
383c0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
383d0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
383e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
383f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
38400 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
38410 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
38420 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
38430 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
38440 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
38450 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
38460 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
38470 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
38480 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
38490 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
384a0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
384b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
384c0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
384d0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
384e0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
384f0 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
38500 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
38510 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
38520 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
38530 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
38540 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
38550 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
38560 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
38570 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
38580 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38590 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
385a0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
385b0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
385c0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
385d0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
385e0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
385f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
38600 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
38610 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
38620 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38630 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
38640 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
38650 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
38660 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
38670 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
38680 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
38690 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
386a0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
386b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
386c0 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20  8           1   
386d0 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34   /* IMP: R-37514
386e0 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e  -35566 */.#defin
386f0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
38700 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20          2    /* 
38710 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36  IMP: R-03371-376
38720 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  37 */.#define SQ
38730 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
38740 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a      3    /* IMP:
38750 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a   R-51971-34154 *
38760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
38770 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
38780 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
38790 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
387a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3