/ Hex Artifact Content
Login

Artifact 9d0ef749ff6492d13686d153e359e07226564be4f70d0cbc46385c8d8d0b96fc:


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 20 3c 2f 75  C_WRITE]..** </u
ccc0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
ccd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
cce0: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
ccf0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
cd00: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
cd10: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
cd20: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
cd30: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
cd40: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
cd50: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
cd60: 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52  E_FCNTL_LAST_ERR
cd70: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NO              
cd80: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
cd90: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
cda0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
cdb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
cdc0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
cdd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
cde0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
cdf0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
ce00: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
ce10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ce20: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
ce30: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
ce40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ce50: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
ce60: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
ce70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ce80: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
ce90: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
cea0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ceb0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
cec0: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
ced0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
cee0: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
cef0: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
cf00: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
cf10: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
cf20: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
cf30: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
cf40: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
cf50: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
cf60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
cf70: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
cf80: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
cf90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
cfa0: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
cfb0: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
cfc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
cfd0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
cfe0: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
cff0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
d000: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
d010: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
d020: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
d030: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
d040: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
d050: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
d060: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
d070: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
d080: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
d090: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
d0a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d0b0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
d0c0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
d0d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
d0e0: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20  CNTL_WAL_BLOCK  
d0f0: 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 23              24.#
d100: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d110: 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 20  NTL_ZIPVFS      
d120: 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 64             25.#d
d130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
d140: 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 20  TL_RBU          
d150: 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64 65            26.#de
d160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
d170: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20 20  L_VFS_POINTER   
d180: 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 65 66           27.#def
d190: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
d1a0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
d1b0: 20 20 20 20 20 20 20 20 32 38 0a 23 64 65 66 69          28.#defi
d1c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
d1d0: 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45  WIN32_GET_HANDLE
d1e0: 20 20 20 20 20 20 20 32 39 0a 23 64 65 66 69 6e         29.#defin
d1f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
d200: 44 42 20 20 20 20 20 20 20 20 20 20 20 20 20 20  DB              
d210: 20 20 20 20 20 20 33 30 0a 23 64 65 66 69 6e 65        30.#define
d220: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45   SQLITE_FCNTL_BE
d230: 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  GIN_ATOMIC_WRITE
d240: 20 20 20 20 20 33 31 0a 23 64 65 66 69 6e 65 20       31.#define 
d250: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
d260: 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45  MIT_ATOMIC_WRITE
d270: 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53      32.#define S
d280: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c  QLITE_FCNTL_ROLL
d290: 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54  BACK_ATOMIC_WRIT
d2a0: 45 20 20 33 33 0a 0a 2f 2a 20 64 65 70 72 65 63  E  33../* deprec
d2b0: 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64  ated names */.#d
d2c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
d2d0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
d2e0: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
d2f0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
d300: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
d310: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
d320: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
d330: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
d340: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
d350: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
d360: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51  O             SQ
d370: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
d380: 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  ERRNO.../*.** CA
d390: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
d3a0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
d3b0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
d3c0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
d3d0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
d3e0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
d3f0: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
d400: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
d410: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
d420: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
d430: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
d440: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
d450: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
d460: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
d470: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
d480: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
d490: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
d4a0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
d4b0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
d4c0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
d4d0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
d4e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
d4f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
d500: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
d510: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
d520: 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e  adable Extension
d530: 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70   Thunk.**.** A p
d540: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70  ointer to the op
d550: 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69  aque sqlite3_api
d560: 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74  _routines struct
d570: 75 72 65 20 69 73 20 70 61 73 73 65 64 20 61 73  ure is passed as
d580: 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70 61  .** the third pa
d590: 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79  rameter to entry
d5a0: 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64   points of [load
d5b0: 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d  able extensions]
d5c0: 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63  .  This.** struc
d5d0: 74 75 72 65 20 6d 75 73 74 20 62 65 20 74 79 70  ture must be typ
d5e0: 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20  edefed in order 
d5f0: 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63  to work around c
d600: 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73  ompiler warnings
d610: 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74  .** on some plat
d620: 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  forms..*/.typede
d630: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
d640: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71  _api_routines sq
d650: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
d660: 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  es;../*.** CAPI3
d670: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
d680: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
d690: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
d6a0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
d6b0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
d6c0: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
d6d0: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
d6e0: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
d6f0: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
d700: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
d710: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
d720: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
d730: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
d740: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
d750: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
d760: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
d770: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
d780: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
d790: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 56 46  on..**.** The VF
d7a0: 53 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  S interface is s
d7b0: 6f 6d 65 74 69 6d 65 73 20 65 78 74 65 6e 64 65  ometimes extende
d7c0: 64 20 62 79 20 61 64 64 69 6e 67 20 6e 65 77 20  d by adding new 
d7d0: 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a 2a 2a 20  methods onto.** 
d7e0: 74 68 65 20 65 6e 64 2e 20 20 45 61 63 68 20 74  the end.  Each t
d7f0: 69 6d 65 20 73 75 63 68 20 61 6e 20 65 78 74 65  ime such an exte
d800: 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c 20 74 68  nsion occurs, th
d810: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
d820: 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d 65 6e 74  .** is increment
d830: 65 64 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ed.  The iVersio
d840: 6e 20 76 61 6c 75 65 20 73 74 61 72 74 65 64 20  n value started 
d850: 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a 2a 20 53  out as 1 in.** S
d860: 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33  QLite [version 3
d870: 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66  .5.0] on [dateof
d880: 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e 20 69 6e  :3.5.0], then in
d890: 63 72 65 61 73 65 64 20 74 6f 20 32 0a 2a 2a 20  creased to 2.** 
d8a0: 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72  with SQLite [ver
d8b0: 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f 6e 20 5b  sion 3.7.0] on [
d8c0: 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d 2c 20 61  dateof:3.7.0], a
d8d0: 6e 64 20 74 68 65 6e 20 69 6e 63 72 65 61 73 65  nd then increase
d8e0: 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74 68 20 53  d.** to 3 with S
d8f0: 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33  QLite [version 3
d900: 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74 65 6f 66  .7.6] on [dateof
d910: 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64 69 74 69  :3.7.6].  Additi
d920: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 6d  onal fields.** m
d930: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
d940: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  o the sqlite3_vf
d950: 73 20 6f 62 6a 65 63 74 20 61 6e 64 20 74 68 65  s object and the
d960: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 0a   iVersion value.
d970: 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61 73 65 20  ** may increase 
d980: 61 67 61 69 6e 20 69 6e 20 66 75 74 75 72 65 20  again in future 
d990: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
d9a0: 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  te..** Note that
d9b0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
d9c0: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
d9d0: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
d9e0: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
d9f0: 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 53 51  ition from.** SQ
da00: 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e  Lite [version 3.
da10: 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73 69 6f 6e  5.9] to [version
da20: 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64 61 74 65   3.6.0] on [date
da30: 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20 61 6e 64  of:3.6.0].** and
da40: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
da50: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 20  n field was not 
da60: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
da70: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
da80: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
da90: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
daa0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
dab0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
dac0: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
dad0: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
dae0: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
daf0: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
db00: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
db10: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
db20: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
db30: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
db40: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
db50: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
db60: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
db70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
db80: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
db90: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
dba0: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
dbb0: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
dbc0: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
dbd0: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
dbe0: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
dbf0: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
dc00: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
dc10: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
dc20: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
dc30: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
dc40: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
dc50: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
dc60: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
dc70: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
dc80: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
dc90: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
dca0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
dcb0: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
dcc0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
dcd0: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
dce0: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
dcf0: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
dd00: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
dd10: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
dd20: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
dd30: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
dd40: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
dd50: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
dd60: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
dd70: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
dd80: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
dd90: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
dda0: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
ddb0: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
ddc0: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
ddd0: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
dde0: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
ddf0: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
de00: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
de10: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  modules..**.** [
de20: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
de30: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  en]].** ^SQLite 
de40: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
de50: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
de60: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
de70: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
de80: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
de90: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
dea0: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
deb0: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20  hname() with an 
dec0: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20  optional suffix 
ded0: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20  added..** ^If a 
dee0: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20  suffix is added 
def0: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  to the zFilename
df00: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77   parameter, it w
df10: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f  ill.** consist o
df20: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63  f a single "-" c
df30: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65  haracter followe
df40: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61  d by no more tha
df50: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d  n.** 11 alphanum
df60: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20  eric and/or "-" 
df70: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e  characters..** ^
df80: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
df90: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
dfa0: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
dfb0: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
dfc0: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
dfd0: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
dfe0: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
dff0: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
e000: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
e010: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
e020: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
e030: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
e040: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
e050: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
e060: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
e070: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
e080: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
e090: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
e0a0: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  to xOpen is a NU
e0b0: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
e0c0: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
e0d0: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
e0e0: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
e0f0: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e  the file.  ^When
e100: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
e110: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e120: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
e130: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
e140: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
e150: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
e160: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
e170: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
e180: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  CLOSE]..**.** Th
e190: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
e1a0: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
e1b0: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
e1c0: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
e1d0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
e1e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
e1f0: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
e200: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
e210: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
e220: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
e230: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
e240: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
e250: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
e260: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
e270: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a  PEN_CREATE]. .**
e280: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
e290: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
e2a0: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
e2b0: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
e2c0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
e2d0: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
e2e0: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
e2f0: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
e300: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53  e set..**.** ^(S
e310: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
e320: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
e330: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
e340: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
e350: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
e360: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
e370: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
e380: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
e390: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
e3a0: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
e3b0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
e3c0: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
e3d0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
e3e0: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
e3f0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e400: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
e410: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
e420: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
e430: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
e440: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
e450: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
e460: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
e470: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
e480: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
e490: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  WAL].** </ul>)^.
e4a0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
e4b0: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
e4c0: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
e4d0: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
e4e0: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
e4f0: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
e500: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
e510: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
e520: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
e530: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
e540: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
e550: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
e560: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
e570: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
e580: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
e590: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
e5a0: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
e5b0: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
e5c0: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
e5d0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
e5e0: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
e5f0: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
e600: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
e610: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
e620: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
e630: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
e640: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
e650: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
e660: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
e670: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
e680: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
e690: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
e6a0: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
e6b0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
e6c0: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
e6d0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
e6e0: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
e6f0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
e700: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
e710: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
e720: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
e730: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
e740: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
e750: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
e760: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
e770: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
e780: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
e790: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
e7a0: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
e7b0: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20  s closed.  ^The 
e7c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
e7d0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77  ETEONCLOSE].** w
e7e0: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54  ill be set for T
e7f0: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e  EMP databases an
e800: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73  d their journals
e810: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64  , transient.** d
e820: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75  atabases, and su
e830: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
e840: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
e850: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
e860: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
e870: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
e880: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
e890: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
e8a0: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
e8b0: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
e8c0: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
e8d0: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
e8e0: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
e8f0: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
e900: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
e910: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
e920: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
e930: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
e940: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
e950: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
e960: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
e970: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
e980: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
e990: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
e9a0: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
e9b0: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
e9c0: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
e9d0: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
e9e0: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
e9f0: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
ea00: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
ea10: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e   access..**.** ^
ea20: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
ea30: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
ea40: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
ea50: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
ea60: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
ea70: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
ea80: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
ea90: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
eaa0: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
eab0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
eac0: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
ead0: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
eae0: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
eaf0: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
eb00: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
eb10: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
eb20: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
eb30: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
eb40: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
eb50: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
eb60: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
eb70: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
eb80: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
eb90: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
eba0: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
ebb0: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
ebc0: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
ebd0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
ebe0: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
ebf0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
ec00: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
ec10: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
ec20: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
ec30: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
ec40: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
ec50: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
ec60: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65  Access]].** ^The
ec70: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
ec80: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
ec90: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
eca0: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
ecb0: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
ecc0: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
ecd0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
ece0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
ecf0: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
ed00: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
ed10: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
ed20: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
ed30: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
ed40: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
ed50: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
ed60: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
ed70: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
ed80: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
ed90: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
eda0: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
edb0: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
edc0: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
edd0: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
ede0: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
edf0: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
ee00: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
ee10: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
ee20: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
ee30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
ee40: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
ee50: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
ee60: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
ee70: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
ee80: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
ee90: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
eea0: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
eeb0: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
eec0: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
eed0: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
eee0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
eef0: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
ef00: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
ef10: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
ef20: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
ef30: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
ef40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
ef50: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
ef60: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
ef70: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
ef80: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
ef90: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
efa0: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
efb0: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
efc0: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
efd0: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
efe0: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
eff0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
f000: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
f010: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
f020: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
f030: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
f040: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
f050: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
f060: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
f070: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
f080: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
f090: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
f0a0: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
f0b0: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
f0c0: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
f0d0: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
f0e0: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
f0f0: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
f100: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
f110: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
f120: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
f130: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
f140: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
f150: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
f160: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
f170: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
f180: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
f190: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
f1a0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
f1b0: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
f1c0: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
f1d0: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
f1e0: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
f1f0: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30  ltiplied by 8640
f200: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72  0000 (the number
f210: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
f220: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75   in .** a 24-hou
f230: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51  r day).  .** ^SQ
f240: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
f250: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
f260: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20  t64() method to 
f270: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a  get the current.
f280: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
f290: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20   if that method 
f2a0: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66  is available (if
f2b0: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f   iVersion is 2 o
f2c0: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e  r .** greater an
f2d0: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  d the function p
f2e0: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
f2f0: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c  LL) and will fal
f300: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75  l back.** to xCu
f310: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78  rrentTime() if x
f320: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
f330: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  () is unavailabl
f340: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53  e..**.** ^The xS
f350: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
f360: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xGetSystemCall()
f370: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65  , and xNestSyste
f380: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  mCall() interfac
f390: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73  es.** are not us
f3a0: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ed by the SQLite
f3b0: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70   core.  These op
f3c0: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65  tional interface
f3d0: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
f3e0: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20  * by some VFSes 
f3f0: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65  to facilitate te
f400: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53  sting of the VFS
f410: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69   code. By overri
f420: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20  ding .** system 
f430: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74  calls with funct
f440: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63  ions under its c
f450: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70  ontrol, a test p
f460: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69  rogram can.** si
f470: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e  mulate faults an
f480: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  d error conditio
f490: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74  ns that would ot
f4a0: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69  herwise be diffi
f4b0: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73  cult.** or impos
f4c0: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e  sible to induce.
f4d0: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73    The set of sys
f4e0: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63  tem calls that c
f4f0: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
f500: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20  .** varies from 
f510: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68  one VFS to anoth
f520: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65  er, and from one
f530: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
f540: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a  same VFS to the.
f550: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
f560: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
f570: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
f580: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65   must be prepare
f590: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20  d for any.** or 
f5a0: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74  all of these int
f5b0: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55  erfaces to be NU
f5c0: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20  LL or for their 
f5d0: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e  behavior to chan
f5e0: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72  ge.** from one r
f5f0: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
f600: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
f610: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d  s must not attem
f620: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20  pt to access.** 
f630: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74  any of these met
f640: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72  hods if the iVer
f650: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20  sion of the VFS 
f660: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a  is less than 3..
f670: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
f680: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
f690: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64  lite3_vfs;.typed
f6a0: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
f6b0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76  3_syscall_ptr)(v
f6c0: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c  oid);.struct sql
f6d0: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
f6e0: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
f6f0: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
f700: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
f710: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20  r (currently 3) 
f720: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
f730: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
f740: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
f750: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
f760: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
f770: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
f780: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
f790: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
f7a0: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
f7b0: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
f7c0: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
f7d0: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
f7e0: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
f7f0: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
f800: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
f810: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
f820: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
f830: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
f840: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
f850: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
f860: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
f870: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
f880: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
f890: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
f8a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
f8b0: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
f8c0: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
f8d0: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
f8e0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
f8f0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
f900: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
f910: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
f920: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
f930: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
f940: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
f950: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
f960: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
f970: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
f980: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
f990: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
f9a0: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
f9b0: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
f9c0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
f9d0: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
f9e0: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
f9f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
fa00: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
fa10: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
fa20: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
fa30: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
fa40: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
fa50: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
fa60: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
fa70: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
fa80: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
fa90: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
faa0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
fab0: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
fac0: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
fad0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
fae0: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
faf0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
fb00: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
fb10: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
fb20: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
fb30: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
fb40: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
fb50: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
fb60: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
fb70: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20  re in version 1 
fb80: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
fb90: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65  s object.  ** de
fba0: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65  finition.  Those
fbb0: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65   that follow are
fbc0: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f   added in versio
fbd0: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a  n 2 or later.  *
fbe0: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  /.  int (*xCurre
fbf0: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
fc00: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
fc10: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
fc20: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
fc30: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
fc40: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
fc50: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
fc60: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54  s object..  ** T
fc70: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66  hose below are f
fc80: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64  or version 3 and
fc90: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20   greater..  */. 
fca0: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65   int (*xSetSyste
fcb0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
fcc0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
fcd0: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
fce0: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20  syscall_ptr);.  
fcf0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
fd00: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d  ptr (*xGetSystem
fd10: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
fd20: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
fd30: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20  zName);.  const 
fd40: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73  char *(*xNextSys
fd50: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
fd60: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
fd70: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a  r *zName);.  /*.
fd80: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
fd90: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
fda0: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68  rsions 1 through
fdb0: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   3 of the sqlite
fdc0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
fdd0: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
fde0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
fdf0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  future versions.
fe00: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
fe10: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
fe20: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
fe30: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
fe40: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
fe50: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
fe60: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
fe70: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
fe80: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
fe90: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
fea0: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
feb0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
fec0: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
fed0: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
fee0: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
fef0: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
ff00: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
ff10: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
ff20: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
ff30: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
ff40: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
ff50: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
ff60: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
ff70: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
ff80: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
ff90: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
ffa0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
ffb0: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
ffc0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
ffd0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
ffe0: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
fff0: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
10000 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
10010 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
10020 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
10030 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
10040 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
10050 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
10060 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
10070 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
10080 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
10090 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
100a0 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
100b0 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
100c0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
100d0 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
100e0 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
100f0 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
10100 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
10110 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
10120 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
10130 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
10140 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
10150 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
10160 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
10170 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
10180 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
10190 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
101a0 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
101b0 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
101c0 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
101d0 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
101e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
101f0 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
10200 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
10210 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
10220 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
10230 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
10240 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
10250 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
10260 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
10270 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
10280 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
10290 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
102a0 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
102b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
102c0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
102d0 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
102e0 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
102f0 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
10300 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
10310 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
10320 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
10330 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
10340 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
10350 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
10360 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
10370 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
10380 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
10390 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
103a0 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
103b0 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
103c0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
103d0 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
103e0 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
103f0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
10400 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
10410 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
10420 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
10430 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
10440 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
10450 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
10460 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
10470 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
10480 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
10490 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
104a0 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
104b0 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   on the correspo
104c0 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
104d0 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
104e0 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
104f0 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
10500 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
10510 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
10520 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
10530 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
10540 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
10550 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
10560 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
10570 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10580 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
10590 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
105a0 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
105b0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
105c0 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
105d0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
105e0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
105f0 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
10600 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
10610 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
10620 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
10630 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
10640 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
10650 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
10660 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
10670 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
10680 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
10690 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
106a0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
106b0 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
106c0 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
106d0 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
106e0 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
106f0 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
10700 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
10710 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
10720 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
10730 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
10740 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
10750 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
10760 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10770 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
10780 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
10790 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
107a0 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
107b0 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
107c0 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
107d0 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
107e0 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
107f0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
10800 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
10810 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
10820 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
10830 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
10840 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
10850 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
10860 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
10870 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
10880 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
10890 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
108a0 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
108b0 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
108c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
108d0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
108e0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
108f0 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
10900 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
10910 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
10920 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
10930 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
10940 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
10950 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
10960 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
10970 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
10980 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
10990 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
109a0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
109b0 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
109c0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
109d0 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
109e0 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
109f0 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
10a00 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
10a10 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
10a20 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
10a30 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
10a40 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
10a50 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
10a60 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
10a70 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
10a80 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
10a90 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
10aa0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
10ab0 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
10ac0 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
10ad0 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
10ae0 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
10af0 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
10b00 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
10b10 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
10b20 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
10b30 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
10b40 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
10b50 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
10b60 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
10b70 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10b80 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
10b90 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
10ba0 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
10bb0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
10bc0 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
10bd0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10be0 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
10bf0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
10c00 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
10c10 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
10c20 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
10c30 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
10c40 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
10c50 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
10c60 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
10c70 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
10c80 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
10c90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
10ca0 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
10cb0 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
10cc0 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
10cd0 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
10ce0 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
10cf0 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
10d00 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
10d10 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
10d20 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
10d30 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
10d40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
10d50 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
10d60 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
10d70 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
10d80 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
10d90 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
10da0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
10db0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
10dc0 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
10dd0 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
10de0 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
10df0 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
10e00 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
10e10 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
10e20 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
10e30 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
10e40 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
10e50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
10e60 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
10e70 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
10e80 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
10e90 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
10ea0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
10eb0 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
10ec0 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
10ed0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
10ee0 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
10ef0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10f00 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
10f10 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
10f20 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
10f30 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
10f40 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
10f50 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
10f60 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
10f70 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
10f80 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
10f90 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
10fa0 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
10fb0 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
10fc0 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
10fd0 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
10fe0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10ff0 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
11000 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
11010 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
11020 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
11030 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
11040 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11050 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
11060 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
11070 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
11080 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
11090 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
110a0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
110b0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
110c0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
110d0 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
110e0 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
110f0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
11100 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
11110 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
11120 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11130 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
11140 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
11150 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
11160 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
11170 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
11180 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
11190 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
111a0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
111b0 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
111c0 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
111d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
111e0 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
111f0 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
11200 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
11210 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
11220 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
11230 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
11240 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
11250 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
11260 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
11270 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
11280 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
11290 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
112a0 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
112b0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
112c0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
112d0 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
112e0 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
112f0 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
11300 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
11310 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
11320 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
11330 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
11340 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
11350 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
11360 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
11370 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
11380 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
11390 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
113a0 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
113b0 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
113c0 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
113d0 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
113e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
113f0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
11400 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
11410 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
11420 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
11430 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
11440 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
11450 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
11460 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
11470 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
11480 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11490 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
114a0 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
114b0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
114c0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
114d0 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
114e0 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
114f0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
11500 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
11510 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
11520 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
11530 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
11540 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
11550 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
11560 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
11570 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
11580 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
11590 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
115a0 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
115b0 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
115c0 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
115d0 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
115e0 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
115f0 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
11600 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
11610 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
11620 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
11630 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
11640 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
11650 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
11660 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
11670 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
11680 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
11690 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
116a0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
116b0 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
116c0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
116d0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
116e0 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
116f0 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
11700 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
11710 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
11720 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
11730 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
11740 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
11750 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11760 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
11770 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
11780 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
11790 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
117a0 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
117b0 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
117c0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
117d0 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
117e0 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
117f0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
11800 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
11810 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
11820 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
11830 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
11840 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
11850 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
11860 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
11870 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
11880 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
11890 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
118a0 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
118b0 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
118c0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
118d0 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
118e0 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
118f0 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
11900 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
11910 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
11920 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
11930 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
11940 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71  .**.** <b>The sq
11950 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
11960 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
11970 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65 20  threadsafe. The 
11980 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
11990 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20  ust ensure that 
119a0 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  no other SQLite 
119b0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
119c0 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a  nvoked by other.
119d0 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65  ** threads while
119e0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
119f0 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62  ) is running.</b
11a00 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
11a10 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
11a20 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e  erface.** may on
11a30 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
11a40 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
11a50 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
11a60 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
11a70 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
11a80 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
11a90 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
11aa0 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
11ab0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11ac0 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
11ad0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
11ae0 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
11af0 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
11b00 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
11b10 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
11b20 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
11b30 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
11b40 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
11b50 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
11b60 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
11b70 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
11b80 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
11b90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
11ba0 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
11bb0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
11bc0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
11bd0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
11be0 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
11bf0 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
11c00 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
11c10 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
11c20 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
11c30 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
11c40 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
11c50 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
11c60 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
11c70 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
11c80 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
11c90 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
11ca0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
11cb0 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
11cc0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
11cd0 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
11ce0 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
11cf0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
11d00 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
11d10 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
11d20 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
11d30 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
11d40 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
11d50 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
11d60 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
11d70 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
11d80 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
11d90 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
11da0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
11db0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11dc0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
11dd0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
11de0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
11df0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
11e00 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
11e10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
11e20 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
11e30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11e40 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
11e50 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
11e60 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
11e70 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
11e80 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
11e90 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
11ea0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
11eb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
11ec0 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
11ed0 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
11ee0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
11ef0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
11f00 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
11f10 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
11f20 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
11f30 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
11f40 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
11f50 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
11f60 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
11f70 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
11f80 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
11f90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11fa0 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
11fb0 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
11fc0 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
11fd0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
11fe0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
11ff0 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
12000 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
12010 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
12020 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
12030 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
12040 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
12050 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
12060 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
12070 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
12080 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
12090 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
120a0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
120b0 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
120c0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
120d0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
120e0 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
120f0 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
12100 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
12110 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
12120 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
12130 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
12140 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
12150 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
12160 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
12170 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
12180 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
12190 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
121a0 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
121b0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
121c0 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
121d0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
121e0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
121f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12200 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
12210 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
12220 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
12230 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
12240 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
12250 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
12260 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
12270 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
12280 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
12290 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
122a0 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
122b0 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
122c0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
122d0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
122e0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
122f0 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
12300 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
12310 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
12320 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
12330 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
12340 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
12350 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
12360 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
12370 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
12380 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
12390 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
123a0 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
123b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
123c0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
123d0 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
123e0 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
123f0 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
12400 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
12410 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
12420 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
12430 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
12440 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
12450 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
12460 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
12470 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
12480 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
12490 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
124a0 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
124b0 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
124c0 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
124d0 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
124e0 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
124f0 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
12500 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
12510 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
12520 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
12530 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
12540 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
12550 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
12560 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
12570 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
12580 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
12590 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
125a0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
125b0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
125c0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
125d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
125e0 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
125f0 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
12600 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
12610 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
12620 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
12630 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
12640 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
12650 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
12660 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
12670 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
12680 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
12690 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
126a0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
126b0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
126c0 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
126d0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
126e0 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
126f0 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
12700 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
12710 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
12720 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
12730 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
12740 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12750 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
12760 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
12770 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
12780 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
12790 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
127a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
127b0 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
127c0 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
127d0 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
127e0 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
127f0 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
12800 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
12810 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
12820 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12830 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
12840 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
12850 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
12860 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
12870 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
12880 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
12890 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
128a0 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
128b0 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
128c0 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
128d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
128e0 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
128f0 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
12900 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
12910 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f  y allocator.  Fo
12920 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
12930 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
12940 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
12950 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
12960 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
12970 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
12980 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
12990 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
129a0 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
129b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
129c0 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
129d0 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
129e0 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
129f0 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
12a00 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
12a10 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
12a20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
12a30 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
12a40 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
12a50 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
12a60 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
12a70 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
12a80 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
12a90 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
12aa0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
12ab0 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
12ac0 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
12ad0 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
12ae0 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
12af0 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
12b00 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
12b10 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
12b20 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
12b30 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
12b40 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
12b50 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
12b60 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
12b70 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
12b80 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
12b90 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
12ba0 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
12bb0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
12bc0 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
12bd0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
12be0 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
12bf0 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
12c00 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
12c10 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
12c20 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
12c30 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
12c40 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
12c50 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
12c60 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
12c70 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
12c80 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
12c90 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
12ca0 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
12cb0 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
12cc0 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
12cd0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
12ce0 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
12cf0 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
12d00 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
12d10 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
12d20 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
12d30 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
12d40 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
12d50 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
12d60 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12d70 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
12d80 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
12d90 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
12da0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
12db0 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
12dc0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
12dd0 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
12de0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
12df0 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
12e00 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
12e10 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
12e20 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
12e30 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
12e40 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
12e50 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
12e60 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
12e70 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
12e80 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
12e90 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
12ea0 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
12eb0 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
12ec0 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
12ed0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
12ee0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
12ef0 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
12f00 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
12f10 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
12f20 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
12f30 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
12f40 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
12f50 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
12f60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
12f70 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
12f80 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
12f90 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
12fa0 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
12fb0 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
12fc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12fd0 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
12fe0 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
12ff0 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
13000 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
13010 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
13020 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
13030 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
13040 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13050 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
13060 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
13070 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
13080 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
13090 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
130a0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
130b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
130c0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
130d0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
130e0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
130f0 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
13100 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
13110 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
13120 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
13130 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
13140 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
13150 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
13160 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
13170 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
13180 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
13190 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
131a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
131b0 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
131c0 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
131d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
131e0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
131f0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
13200 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13210 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
13220 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
13230 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13240 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
13250 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13260 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
13270 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
13280 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
13290 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
132a0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
132b0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
132c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
132d0 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
132e0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
132f0 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
13300 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
13310 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
13320 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
13330 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
13340 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
13350 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
13360 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
13370 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
13380 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
13390 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
133a0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
133b0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
133c0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
133d0 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
133e0 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
133f0 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
13400 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
13410 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
13420 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
13430 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
13440 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
13450 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
13460 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
13470 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
13480 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
13490 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
134a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
134b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
134c0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
134d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
134e0 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
134f0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
13500 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
13510 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
13520 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
13530 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
13540 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
13550 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
13560 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
13570 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
13580 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
13590 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
135a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
135b0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
135c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
135d0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
135e0 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
135f0 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
13600 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
13610 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
13620 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
13630 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
13640 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
13650 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
13660 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
13670 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
13680 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
13690 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
136a0 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
136b0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
136c0 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
136d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
136e0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
136f0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
13700 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
13710 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
13720 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
13730 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
13740 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13750 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
13760 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
13770 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
13780 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
13790 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
137a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
137b0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
137c0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
137d0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
137e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
137f0 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
13800 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
13810 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13820 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
13830 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
13840 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
13850 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
13860 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
13870 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
13880 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
13890 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
138a0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
138b0 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
138c0 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
138d0 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
138e0 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
138f0 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
13900 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
13910 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
13920 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13930 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
13940 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
13950 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
13960 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
13970 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
13980 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
13990 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
139a0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
139b0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
139c0 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
139d0 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
139e0 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
139f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
13a00 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
13a10 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
13a20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
13a30 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
13a40 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
13a50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13a60 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
13a70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
13a80 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
13a90 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
13aa0 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
13ab0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13ac0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13ad0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13ae0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13af0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
13b00 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13b10 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
13b20 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
13b30 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
13b40 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
13b50 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
13b60 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
13b70 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
13b80 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
13b90 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
13ba0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
13bb0 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
13bc0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
13bd0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13be0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
13bf0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13c00 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
13c10 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
13c20 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
13c30 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
13c40 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13c50 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
13c60 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
13c70 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
13c80 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13c90 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
13ca0 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
13cb0 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
13cc0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
13cd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13ce0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
13cf0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
13d00 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
13d10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
13d20 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
13d30 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
13d40 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
13d50 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
13d60 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
13d70 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
13d80 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
13d90 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
13da0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
13db0 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
13dc0 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
13dd0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13de0 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
13df0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13e00 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
13e10 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
13e20 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
13e30 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
13e40 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
13e50 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
13e60 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
13e70 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
13e80 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
13e90 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
13ea0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
13eb0 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
13ec0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
13ed0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
13ee0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
13ef0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13f00 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
13f10 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
13f20 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
13f30 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
13f40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13f50 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
13f60 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
13f70 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
13f80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
13f90 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
13fa0 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
13fb0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
13fc0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13fd0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c  ITE_CONFIG_SMALL
13fe0 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
13ff0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c  LITE_CONFIG_SMAL
14000 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  L_MALLOC</dt>.**
14010 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
14020 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d  E_CONFIG_SMALL_M
14030 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
14040 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
14050 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20 69 6e  nt of.** type in
14060 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
14070 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69  s a boolean, whi
14080 63 68 20 69 66 20 74 72 75 65 20 70 72 6f 76 69  ch if true provi
14090 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a 2a 2a  des a hint to.**
140a0 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
140b0 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c 61 72  should avoid lar
140c0 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ge memory alloca
140d0 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69 62 6c  tions if possibl
140e0 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  e..** SQLite wil
140f0 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69 66 20  l run faster if 
14100 69 74 20 69 73 20 66 72 65 65 20 74 6f 20 6d 61  it is free to ma
14110 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20  ke large memory 
14120 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a 2a 20  allocations,.** 
14130 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69 63 61  but some applica
14140 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65 66 65  tion might prefe
14150 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65 72 20  r to run slower 
14160 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f 72 0a  in exchange for.
14170 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 61 62  ** guarantees ab
14180 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61 67 6d  out memory fragm
14190 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 61 72  entation that ar
141a0 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20 6c 61  e possible if la
141b0 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  rge.** allocatio
141c0 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64 2e 20  ns are avoided. 
141d0 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f   This hint is no
141e0 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a 20 3c  rmally off..** <
141f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14200 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
14210 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
14220 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
14230 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
14240 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
14250 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74  IG_MEMSTATUS opt
14260 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
14270 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
14280 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70  e int,.** interp
14290 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
142a0 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
142b0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
142c0 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a  e collection of.
142d0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
142e0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e  tion statistics.
142f0 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
14300 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14310 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  tics are.** disa
14320 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  bled, the follow
14330 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
14340 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
14350 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
14360 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
14370 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
14380 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
14390 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
143a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
143b0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
143c0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
143d0 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
143e0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
143f0 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  us64()].**   </u
14400 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
14410 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
14420 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
14430 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
14440 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
14450 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
14460 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
14470 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
14480 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
14490 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
144a0 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
144b0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
144c0 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
144d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
144e0 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e  G_SCRATCH]] <dt>
144f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
14500 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
14510 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
14520 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74  NFIG_SCRATCH opt
14530 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ion is no longer
14540 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a   used..** </dd>.
14550 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14560 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
14570 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14580 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
14590 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
145a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
145b0 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73  GECACHE option s
145c0 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72  pecifies a memor
145d0 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53  y pool.** that S
145e0 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
145f0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  r the database p
14600 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74  age cache with t
14610 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a  he default page.
14620 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
14630 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  ntation.  .** Th
14640 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
14650 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d   option is a no-
14660 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61  op if an applica
14670 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65  tion-define page
14680 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
14690 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64  entation is load
146a0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51  ed using the [SQ
146b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
146c0 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  HE2]..** ^There 
146d0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
146e0 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
146f0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20  NFIG_PAGECACHE: 
14700 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  A pointer to.** 
14710 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d  8-byte aligned m
14720 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68  emory (pMem), th
14730 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
14740 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28  age cache line (
14750 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
14760 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20  number of cache 
14770 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  lines (N)..** Th
14780 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
14790 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
147a0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
147b0 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
147c0 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
147d0 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
147e0 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d   65536) plus som
147f0 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f  e extra bytes fo
14800 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68  r each.** page h
14810 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d  eader.  ^The num
14820 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74  ber of extra byt
14830 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65  es needed by the
14840 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20   page header.** 
14850 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
14860 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f  d using [SQLITE_
14870 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
14880 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20  RSZ]..** ^It is 
14890 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
148a0 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
148b0 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74  memory,.** for t
148c0 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20  he sz parameter 
148d0 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  to be larger tha
148e0 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68  n necessary.  Th
148f0 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65  e pMem.** argume
14900 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  nt must be eithe
14910 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
14920 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   or a pointer to
14930 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
14940 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d  igned block of m
14950 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73  emory of at leas
14960 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74  t sz*N bytes, ot
14970 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65  herwise.** subse
14980 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69  quent behavior i
14990 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
149a0 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f  ^When pMem is no
149b0 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
149c0 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73  ill strive to us
149d0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
149e0 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69  vided.** to sati
149f0 73 66 79 20 70 61 67 65 20 63 61 63 68 65 20 6e  sfy page cache n
14a00 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61  eeds, falling ba
14a10 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  ck to [sqlite3_m
14a20 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61  alloc()] if.** a
14a30 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65   page cache line
14a40 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20   is larger than 
14a50 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 61  sz bytes or if a
14a60 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62  ll of the pMem b
14a70 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61  uffer.** is exha
14a80 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d  usted..** ^If pM
14a90 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e  em is NULL and N
14aa0 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   is non-zero, th
14ab0 65 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65  en each database
14ac0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64   connection.** d
14ad0 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62  oes an initial b
14ae0 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ulk allocation f
14af0 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  or page cache me
14b00 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  mory.** from [sq
14b10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
14b20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e  sufficient for N
14b30 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20   cache lines if 
14b40 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72  N is positive or
14b50 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62  .** of -1024*N b
14b60 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67  ytes if N is neg
14b70 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64  ative, . ^If add
14b80 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
14b90 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
14ba0 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
14bb0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
14bc0 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a  y the initial.**
14bd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
14be0 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  n SQLite goes to
14bf0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14c00 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66  ()] separately f
14c10 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74  or each.** addit
14c20 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65  ional cache line
14c30 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
14c40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
14c50 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AP]] <dt>SQLITE_
14c60 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
14c70 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
14c80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
14c90 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
14ca0 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
14cb0 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61  y buffer .** tha
14cc0 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
14cd0 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
14ce0 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
14cf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
14d00 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  .** beyond those
14d10 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79   provided for by
14d20 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
14d30 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e  PAGECACHE]..** ^
14d40 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14d50 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73  G_HEAP option is
14d60 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
14d70 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
14d80 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69  piled.** with ei
14d90 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
14da0 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20  BLE_MEMSYS3] or 
14db0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
14dc0 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75  EMSYS5] and retu
14dd0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rns.** [SQLITE_E
14de0 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64  RROR] if invoked
14df0 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e   otherwise..** ^
14e00 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
14e10 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
14e20 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a  ITE_CONFIG_HEAP:
14e30 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  .** An 8-byte al
14e40 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
14e50 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
14e60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
14e70 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
14e80 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
14e90 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
14ea0 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
14eb0 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
14ec0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
14ed0 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
14ee0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
14ef0 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
14f00 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
14f10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
14f20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
14f30 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
14f40 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
14f50 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
14f60 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
14f70 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
14f80 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
14f90 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
14fa0 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  t NULL then the 
14fb0 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
14fc0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
14fd0 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
14fe0 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
14ff0 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
15000 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
15010 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
15020 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
15030 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
15040 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
15050 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
15060 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
15070 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
15080 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
15090 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d  ed..** The minim
150a0 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
150b0 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20  ze is capped at 
150c0 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c  2**12. Reasonabl
150d0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20  e values.** for 
150e0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
150f0 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20  cation size are 
15100 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a  2**5 through 2**
15110 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  8.</dd>.**.** [[
15120 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15130 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
15140 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
15150 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
15160 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15170 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65  UTEX option take
15180 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15190 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a  ent which is a.*
151a0 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
151b0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
151c0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
151d0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
151e0 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
151f0 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c 74  nt specifies alt
15200 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
15210 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
15220 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20  s to be used.** 
15230 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74  in place the mut
15240 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
15250 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
15260 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
15270 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
15280 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
15290 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
152a0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
152b0 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
152c0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
152d0 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
152e0 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
152f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
15300 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
15310 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
15320 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
15330 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
15340 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
15350 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
15360 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
15370 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
15380 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
15390 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
153a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
153b0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
153c0 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
153d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
153e0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
153f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
15400 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15410 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
15420 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
15430 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
15440 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15450 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15460 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e  _GETMUTEX option
15470 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15480 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
15490 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
154a0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
154b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
154c0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
154d0 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
154e0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
154f0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
15500 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
15510 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
15520 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
15530 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
15540 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
15550 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
15560 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
15570 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
15580 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
15590 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
155a0 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
155b0 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
155c0 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
155d0 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
155e0 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
155f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
15600 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
15610 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
15620 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
15630 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
15640 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
15650 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
15660 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
15670 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
15680 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
15690 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
156a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
156b0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
156c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
156d0 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
156e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
156f0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
15700 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
15710 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15720 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
15730 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15740 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
15750 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
15760 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15770 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20  OOKASIDE option 
15780 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
15790 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
157a0 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  ne.** the defaul
157b0 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73  t size of lookas
157c0 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61  ide memory on ea
157d0 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ch [database con
157e0 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65  nection]..** The
157f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15800 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
15810 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
15820 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
15830 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
15840 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
15850 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
15860 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
15870 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
15880 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ^(SQLITE_CONFIG_
15890 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74  LOOKASIDE.** set
158a0 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74  s the <i>default
158b0 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
158c0 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
158d0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
158e0 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74  IDE].** option t
158f0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
15900 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75  nfig()] can be u
15910 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
15920 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63  e lookaside.** c
15930 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20  onfiguration on 
15940 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65  individual conne
15950 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a  ctions.)^ </dd>.
15960 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15970 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20  ONFIG_PCACHE2]] 
15980 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15990 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  G_PCACHE2</dt>.*
159a0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
159b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
159c0 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  E2 option takes 
159d0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
159e0 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
159f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
15a00 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
15a10 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
15a20 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
15a30 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69  ecifies.** the i
15a40 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 75  nterface to a cu
15a50 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
15a60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
15a70 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b  ^.** ^SQLite mak
15a80 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
15a90 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
15aa0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
15ab0 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  t.</dd>.**.** [[
15ac0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15ad0 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
15ae0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15af0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
15b00 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
15b10 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15b20 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
15b30 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
15b40 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
15b50 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
15b60 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
15b70 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
15b80 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
15b90 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e  of.** the curren
15ba0 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
15bb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
15bc0 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
15bd0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15be0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
15bf0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15c00 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
15c10 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
15c20 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
15c30 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  n is used to con
15c40 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74  figure the SQLit
15c50 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72  e.** global [err
15c60 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68  or log]..** (^Th
15c70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15c80 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
15c90 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
15ca0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
15cb0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
15cc0 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
15cd0 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
15ce0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
15cf0 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
15d00 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
15d10 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
15d20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
15d30 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
15d40 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
15d50 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
15d60 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
15d70 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
15d80 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
15d90 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
15da0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
15db0 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
15dc0 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
15dd0 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
15de0 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
15df0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
15e00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15e10 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
15e20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
15e30 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
15e40 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
15e50 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
15e60 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
15e70 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
15e80 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
15e90 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
15ea0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
15eb0 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
15ec0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
15ed0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15ee0 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
15ef0 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
15f00 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
15f10 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
15f20 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
15f30 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
15f40 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
15f50 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
15f60 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
15f70 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
15f80 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
15f90 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
15fa0 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
15fb0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
15fc0 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
15fd0 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
15fe0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
15ff0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
16000 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
16010 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
16020 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
16030 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
16040 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
16050 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
16060 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
16070 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
16080 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
16090 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
160a0 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
160b0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
160c0 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
160d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
160e0 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65  URI.** <dd>^(The
160f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
16100 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  RI option takes 
16110 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
16120 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a  t of type int..*
16130 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  * If non-zero, t
16140 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
16150 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
16160 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
16170 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a  ameter is zero,.
16180 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  ** then URI hand
16190 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
161a0 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66   disabled.)^ ^If
161b0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
161c0 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61   globally.** ena
161d0 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61  bled, all filena
161e0 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73  mes passed to [s
161f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
16200 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
16210 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
16220 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a  _open16()] or.**
16230 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
16240 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63  rt of [ATTACH] c
16250 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65  ommands are inte
16260 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c  rpreted as URIs,
16270 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
16280 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
16290 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
162a0 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73  N_URI] flag is s
162b0 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  et when the data
162c0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
162d0 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49  on is opened. ^I
162e0 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
162f0 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
16300 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
16310 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
16320 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
16330 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
16340 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
16350 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
16360 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
16370 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c  d. ^(By default,
16380 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
16390 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73   globally.** dis
163a0 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75  abled. The defau
163b0 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20  lt value may be 
163c0 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69  changed by compi
163d0 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a  ling with the.**
163e0 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
163f0 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  ] symbol defined
16400 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
16410 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
16420 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20  NG_INDEX_SCAN]] 
16430 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16440 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
16450 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68  _SCAN.** <dd>^Th
16460 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16470 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
16480 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  CAN option takes
16490 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
164a0 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68  r.** argument wh
164b0 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
164c0 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20  ed as a boolean 
164d0 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
164e0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a  le or disable.**
164f0 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
16500 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
16510 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
16520 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
16530 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68  ptimizer..** ^Th
16540 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
16550 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
16560 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
16570 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
16580 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
16590 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
165a0 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
165b0 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
165c0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
165d0 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
165e0 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
165f0 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
16600 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
16610 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
16620 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
16630 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
16640 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
16650 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
16660 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
16670 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69   when the optimi
16680 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  zation is enable
16690 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68  d.  Providing th
166a0 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20  e ability to.** 
166b0 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69  disable the opti
166c0 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  mization allows 
166d0 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79  the older, buggy
166e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
166f0 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
16700 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e  hout change even
16710 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73   with newer vers
16720 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
16730 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16740 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b  ONFIG_PCACHE]] [
16750 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
16760 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64  ETPCACHE]].** <d
16770 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16780 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54  PCACHE and SQLIT
16790 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
167a0 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65  HE.** <dd> These
167b0 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73   options are obs
167c0 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64  olete and should
167d0 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
167e0 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65  new code..** The
167f0 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  y are retained f
16800 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
16810 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61  patibility but a
16820 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a  re now no-ops..*
16830 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
16840 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
16850 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  LLOG]].** <dt>SQ
16860 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
16870 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  OG.** <dd>This o
16880 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
16890 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74  ailable if sqlit
168a0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
168b0 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
168c0 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d  E_ENABLE_SQLLOG]
168d0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
168e0 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68  acro defined. Th
168f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16900 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20   should.** be a 
16910 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
16920 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f  ction of type vo
16930 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
16940 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  te3*,const char*
16950 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73  , int)..** The s
16960 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  econd should be 
16970 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e  of type (void*).
16980 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
16990 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20   invoked by the 
169a0 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68  library.** in th
169b0 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72  ree separate cir
169c0 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e  cumstances, iden
169d0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61  tified by the va
169e0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
169f0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
16a00 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f  meter. If the fo
16a10 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
16a20 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61  s 0, then the da
16a30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16a40 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  n.** passed as t
16a50 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16a60 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  nt has just been
16a70 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69   opened. The thi
16a80 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70  rd argument.** p
16a90 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
16aa0 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  r containing the
16ab0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69   name of the mai
16ac0 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
16ad0 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
16ae0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31  h parameter is 1
16af0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73  , then the SQL s
16b00 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68  tatement that th
16b10 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
16b20 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68  r.** points to h
16b30 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65  as just been exe
16b40 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68  cuted. Or, if th
16b50 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
16b60 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a  er is 2, then.**
16b70 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
16b80 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20  being passed as 
16b90 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
16ba0 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c  eter is being cl
16bb0 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69  osed. The.** thi
16bc0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
16bd0 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74  passed NULL In t
16be0 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78  his case.  An ex
16bf0 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74  ample of using t
16c00 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  his.** configura
16c10 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20  tion option can 
16c20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22  be seen in the "
16c30 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73  test_sqllog.c" s
16c40 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a  ource file in.**
16c50 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53   the canonical S
16c60 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65  QLite source tre
16c70 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  e.</dd>.**.** [[
16c80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
16c90 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  AP_SIZE]].** <dt
16ca0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
16cb0 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  MAP_SIZE.** <dd>
16cc0 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  ^SQLITE_CONFIG_M
16cd0 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74  MAP_SIZE takes t
16ce0 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  wo 64-bit intege
16cf0 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  r (sqlite3_int64
16d00 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  ) values.** that
16d10 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74   are the default
16d20 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
16d30 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65   (the default se
16d40 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52  tting for.** [PR
16d50 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29  AGMA mmap_size])
16d60 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
16d70 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
16d80 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68  ze limit..** ^Th
16d90 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
16da0 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  g can be overrid
16db0 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61  den by each data
16dc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16dd0 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20  using.** either 
16de0 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  the [PRAGMA mmap
16df0 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20  _size] command, 
16e00 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a  or by using the.
16e10 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
16e20 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
16e30 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65   control.  ^(The
16e40 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
16e50 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69   mmap size.** wi
16e60 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74  ll be silently t
16e70 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65  runcated if nece
16e80 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 74  ssary so that it
16e90 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64   does not exceed
16ea0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d   the.** compile-
16eb0 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61  time maximum mma
16ec0 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68  p size set by th
16ed0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  e.** [SQLITE_MAX
16ee0 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70  _MMAP_SIZE] comp
16ef0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
16f00 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72  )^.** ^If either
16f10 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
16f20 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61  s option is nega
16f30 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20  tive, then that 
16f40 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63  argument is.** c
16f50 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f  hanged to its co
16f60 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75  mpile-time defau
16f70 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  lt..**.** [[SQLI
16f80 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
16f90 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  HEAPSIZE]].** <d
16fa0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16fb0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a  WIN32_HEAPSIZE.*
16fc0 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
16fd0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
16fe0 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69  EAPSIZE option i
16ff0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
17000 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a   if SQLite is.**
17010 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69   compiled for Wi
17020 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b  ndows with the [
17030 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c  SQLITE_WIN32_MAL
17040 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOC] pre-process
17050 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69  or macro.** defi
17060 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e  ned. ^SQLITE_CON
17070 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
17080 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69  ZE takes a 32-bi
17090 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
170a0 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74  er value.** that
170b0 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d   specifies the m
170c0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74  aximum size of t
170d0 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e  he created heap.
170e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
170f0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
17100 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  RSZ]].** <dt>SQL
17110 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17120 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  E_HDRSZ.** <dd>^
17130 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
17140 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f  G_PCACHE_HDRSZ o
17150 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
17160 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
17170 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
17180 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
17190 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  er and writes in
171a0 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
171b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
171c0 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72  tra.** bytes per
171d0 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66   page required f
171e0 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20  or each page in 
171f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
17200 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
17210 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72  e amount of extr
17220 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64  a space required
17230 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65   can change depe
17240 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d  nding on the com
17250 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74  piler,.** target
17260 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53   platform, and S
17270 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a  QLite version..*
17280 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17290 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20  NFIG_PMASZ]].** 
172a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
172b0 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  G_PMASZ.** <dd>^
172c0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
172d0 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74  G_PMASZ option t
172e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61  akes a single pa
172f0 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
17300 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
17310 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 73  integer and sets
17320 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d   the "Minimum PM
17330 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20  A Size" for the 
17340 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a  multithreaded.**
17350 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20   sorter to that 
17360 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 65  integer.  The de
17370 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d  fault minimum PM
17380 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79  A Size is set by
17390 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
173a0 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f  SORTER_PMASZ] co
173b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
173c0 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 20  n.  New threads 
173d0 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20  are launched.** 
173e0 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72  to help with sor
173f0 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65  t operations whe
17400 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  n multithreaded 
17410 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e  sorting.** is en
17420 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65  abled (using the
17430 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 73   [PRAGMA threads
17440 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74  ] command) and t
17450 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e  he amount of con
17460 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f  tent.** to be so
17470 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68 65  rted exceeds the
17480 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73   page size times
17490 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20   the minimum of 
174a0 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63  the.** [PRAGMA c
174b0 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69  ache_size] setti
174c0 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75  ng and this valu
174d0 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
174e0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
174f0 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74  L_SPILL]].** <dt
17500 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
17510 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a  TMTJRNL_SPILL.**
17520 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17530 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c  _CONFIG_STMTJRNL
17540 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61  _SPILL option ta
17550 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
17560 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
17570 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61  becomes the [sta
17580 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20  tement journal] 
17590 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68  spill-to-disk th
175a0 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53  reshold.  .** [S
175b0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
175c0 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d  s] are held in m
175d0 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69  emory until thei
175e0 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73  r size (in bytes
175f0 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69  ).** exceeds thi
17600 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20  s threshold, at 
17610 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79  which point they
17620 20 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20   are written to 
17630 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74  disk..** Or if t
17640 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20  he threshold is 
17650 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f  -1, statement jo
17660 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79  urnals are alway
17670 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73  s held.** exclus
17680 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e  ively in memory.
17690 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73  .** Since many s
176a0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
176b0 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c  s never become l
176c0 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68  arge, setting th
176d0 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73  e spill.** thres
176e0 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20  hold to a value 
176f0 73 75 63 68 20 61 73 20 36 34 4b 69 42 20 63 61  such as 64KiB ca
17700 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75 63 65  n greatly reduce
17710 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a   the amount of.*
17720 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74  * I/O required t
17730 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d  o support statem
17740 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  ent rollback..**
17750 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
17760 75 65 20 66 6f 72 20 74 68 69 73 20 73 65 74 74  ue for this sett
17770 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65  ing is controlle
17780 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  d by the.** [SQL
17790 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  ITE_STMTJRNL_SPI
177a0 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  LL] compile-time
177b0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c   option..** </dl
177c0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
177d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
177e0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
177f0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
17800 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
17810 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
17820 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
17830 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
17840 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
17850 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
17860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
17870 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
17880 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
17890 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
178a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
178b0 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
178c0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
178d0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
178e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
178f0 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
17900 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20  6  /* No longer 
17910 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  used */.#define 
17920 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
17930 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
17940 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
17950 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
17960 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17970 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
17980 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
17990 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
179a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
179b0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
179c0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
179d0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
179e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
179f0 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
17a00 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
17a10 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
17a20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17a30 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
17a40 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
17a50 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
17a60 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
17a70 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
17a80 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
17a90 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
17aa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17ab0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17ac0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
17ad0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
17ae0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
17af0 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
17b00 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
17b10 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
17b20 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
17b30 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
17b40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17b50 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
17b60 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
17b70 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
17b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
17b90 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
17ba0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
17bb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17bc0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
17bd0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
17be0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
17bf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17c00 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
17c10 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
17c20 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
17c30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17c40 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
17c50 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
17c60 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
17c70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17c80 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
17c90 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
17ca0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
17cb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
17cc0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
17cd0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
17ce0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
17cf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17d00 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
17d10 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
17d20 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
17d30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17d40 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
17d50 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20  Z        24  /* 
17d60 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66  int *psz */.#def
17d70 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17d80 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20  G_PMASZ         
17d90 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73        25  /* uns
17da0 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20  igned int szPma 
17db0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17dc0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
17dd0 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20  L_SPILL      26 
17de0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
17df0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17e00 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 4c  CONFIG_SMALL_MAL
17e10 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20 20 2f  LOC        27  /
17e20 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 0a 2f 2a  * boolean */../*
17e30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
17e40 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
17e50 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
17e60 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
17e70 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
17e80 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
17e90 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
17ea0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
17eb0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
17ec0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
17ed0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
17ee0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
17ef0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
17f00 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
17f10 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17f20 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
17f30 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
17f40 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
17f50 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
17f60 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17f70 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
17f80 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
17f90 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
17fa0 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
17fb0 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
17fc0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17fd0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
17fe0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
17ff0 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
18000 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
18010 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
18020 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
18030 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
18040 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
18050 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
18060 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
18070 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
18080 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
18090 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
180a0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
180b0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
180c0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
180d0 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
180e0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
180f0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
18100 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
18110 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
18120 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
18130 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
18140 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
18150 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
18160 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
18170 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
18180 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
18190 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
181a0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
181b0 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
181c0 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
181d0 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
181e0 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
181f0 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
18200 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
18210 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
18220 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
18230 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
18240 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
18250 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
18260 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
18270 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
18280 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
18290 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
182a0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
182b0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
182c0 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
182d0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
182e0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
182f0 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
18300 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
18310 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18320 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
18330 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
18340 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
18350 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
18360 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
18370 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
18380 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
18390 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
183a0 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
183b0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
183c0 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
183d0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
183e0 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
183f0 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
18400 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
18410 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
18420 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
18430 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
18440 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
18450 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
18460 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
18470 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18480 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
18490 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
184a0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
184b0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
184c0 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
184d0 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
184e0 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
184f0 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
18500 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
18510 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
18520 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
18530 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
18540 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
18550 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
18560 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
18570 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
18580 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
18590 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
185a0 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
185b0 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
185c0 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
185d0 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
185e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
185f0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
18600 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18610 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
18620 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
18630 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
18640 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
18650 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
18660 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
18670 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
18680 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
18690 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
186a0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
186b0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
186c0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
186d0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
186e0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
186f0 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
18700 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
18710 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
18720 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
18730 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
18740 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
18750 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
18760 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
18770 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
18780 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
18790 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
187a0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
187b0 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
187c0 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
187d0 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
187e0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
187f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18800 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
18810 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
18820 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
18830 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
18840 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
18850 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
18860 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18870 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18880 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
18890 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
188a0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
188b0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
188c0 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
188d0 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
188e0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
188f0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18900 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
18910 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18920 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
18930 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
18940 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
18950 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
18960 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
18970 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
18980 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
18990 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
189a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
189b0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
189c0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
189d0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
189e0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
189f0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
18a00 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
18a10 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
18a20 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
18a30 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
18a40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18a50 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
18a60 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
18a70 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
18a80 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
18a90 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
18aa0 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
18ab0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18ac0 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
18ad0 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a  OKENIZER</dt>.**
18ae0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
18af0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
18b00 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
18b10 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74  the two-argument
18b20 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  .** version of t
18b30 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  he [fts3_tokeniz
18b40 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77  er()] function w
18b50 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20  hich is part of 
18b60 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75  the.** [FTS3] fu
18b70 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65  ll-text search e
18b80 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e  ngine extension.
18b90 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18ba0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18bb0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18bc0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
18bd0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
18be0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
18bf0 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b  disable fts3_tok
18c00 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70  enizer() or.** p
18c10 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
18c20 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  e fts3_tokenizer
18c30 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  () or negative t
18c40 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
18c50 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ing.** unchanged
18c60 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
18c70 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
18c80 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
18c90 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
18ca0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
18cb0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
18cc0 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f   whether fts3_to
18cd0 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62  kenizer is disab
18ce0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
18cf0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
18d00 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
18d10 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
18d20 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
18d30 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
18d40 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74  case the new set
18d50 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
18d60 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
18d70 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
18d80 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18d90 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e  E_LOAD_EXTENSION
18da0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
18db0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
18dc0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
18dd0 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c  disable the [sql
18de0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
18df0 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  ion()].** interf
18e00 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c  ace independentl
18e10 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65  y of the [load_e
18e20 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20  xtension()] SQL 
18e30 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  function..** The
18e40 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
18e50 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
18e60 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f  )] API enables o
18e70 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20  r disables both 
18e80 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71  the.** C-API [sq
18e90 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
18ea0 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20  sion()] and the 
18eb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f  SQL function [lo
18ec0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e  ad_extension()].
18ed0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18ee0 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18ef0 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18f00 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20   When the first 
18f10 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73  argument to this
18f20 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c   interface is 1,
18f30 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43   then only the C
18f40 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c  -API is.** enabl
18f50 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  ed and the SQL f
18f60 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20  unction remains 
18f70 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68  disabled.  If th
18f80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18f90 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65   to.** this inte
18fa0 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e  rface is 0, then
18fb0 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20   both the C-API 
18fc0 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
18fd0 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65  tion are disable
18fe0 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72  d..** If the fir
18ff0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d  st argument is -
19000 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67  1, then no chang
19010 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73  es are made to s
19020 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74  tate of either t
19030 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74  he.** C-API or t
19040 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
19050 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
19060 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
19070 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
19080 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
19090 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
190a0 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
190b0 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33  whether [sqlite3
190c0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
190d0 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
190e0 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
190f0 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67  nabled following
19100 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
19110 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19120 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55  r may.** be a NU
19130 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77  LL pointer, in w
19140 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65  hich case the ne
19150 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  w setting is not
19160 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a   reported back..
19170 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
19180 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
19190 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64  IG_MAINDBNAME</d
191a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
191b0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
191c0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61  to change the na
191d0 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22  me of the "main"
191e0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68   database.** sch
191f0 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20  ema.  ^The sole 
19200 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
19210 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74  inter to a const
19220 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a  ant UTF8 string.
19230 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
19240 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68  come the new sch
19250 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63  ema name in plac
19260 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53  e of "main".  ^S
19270 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  QLite.** does no
19280 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  t make a copy of
19290 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63   the new main sc
192a0 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67  hema name string
192b0 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61  , so the applica
192c0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73  tion.** must ens
192d0 75 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67  ure that the arg
192e0 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74  ument passed int
192f0 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20  o this DBCONFIG 
19300 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e  option is unchan
19310 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74  ged.** until aft
19320 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  er the database 
19330 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
19340 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
19350 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
19360 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e  ONFIG_NO_CKPT_ON
19370 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  _CLOSE</dt>.** <
19380 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65  dd> Usually, whe
19390 6e 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20  n a database in 
193a0 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73  wal mode is clos
193b0 65 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66  ed or detached f
193c0 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61  rom a .** databa
193d0 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74  se handle, SQLit
193e0 65 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73  e checks if this
193f0 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20   will mean that 
19400 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f  there are now no
19410 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   .** connections
19420 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64   at all to the d
19430 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20  atabase. If so, 
19440 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68  it performs a ch
19450 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65  eckpoint .** ope
19460 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c  ration before cl
19470 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63  osing the connec
19480 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f  tion. This optio
19490 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  n may be used to
194a0 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69  .** override thi
194b0 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65  s behaviour. The
194c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
194d0 20 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20   passed to this 
194e0 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  operation.** is 
194f0 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e  an integer - non
19500 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65  -zero to disable
19510 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d   checkpoints-on-
19520 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28  close, or zero (
19530 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20  the.** default) 
19540 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20  to enable them. 
19550 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19560 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
19570 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  r to an integer.
19580 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73  ** into which is
19590 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
195a0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
195b0 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d  her checkpoints-
195c0 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65  on-close.** have
195d0 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d   been disabled -
195e0 20 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e   0 if they are n
195f0 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69  ot disabled, 1 i
19600 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c  f they are..** <
19610 2f 64 64 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  /dd>.** <dt>SQLI
19620 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19630 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a 2a 20  LE_QPSG</dt>.** 
19640 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45  <dd>^(The SQLITE
19650 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19660 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20 61 63 74  _QPSG option act
19670 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 74 69  ivates or deacti
19680 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 5b 71 75  vates.** the [qu
19690 65 72 79 20 70 6c 61 6e 6e 65 72 20 73 74 61 62  ery planner stab
196a0 69 6c 69 74 79 20 67 75 61 72 61 6e 74 65 65 5d  ility guarantee]
196b0 20 28 51 50 53 47 29 2e 20 20 57 68 65 6e 20 74   (QPSG).  When t
196c0 68 65 20 51 50 53 47 20 69 73 20 61 63 74 69 76  he QPSG is activ
196d0 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 53  e,.** a single S
196e0 51 4c 20 71 75 65 72 79 20 73 74 61 74 65 6d 65  QL query stateme
196f0 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75  nt will always u
19700 73 65 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  se the same algo
19710 72 69 74 68 6d 20 72 65 67 61 72 64 6c 65 73 73  rithm regardless
19720 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73 20 6f 66  .** of values of
19730 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
19740 72 73 5d 2e 29 5e 20 54 68 65 20 51 50 53 47 20  rs].)^ The QPSG 
19750 64 69 73 61 62 6c 65 73 20 73 6f 6d 65 20 71 75  disables some qu
19760 65 72 79 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ery optimization
19770 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b 20 61  s.** that look a
19780 74 20 74 68 65 20 76 61 6c 75 65 73 20 6f 66 20  t the values of 
19790 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
197a0 2c 20 77 68 69 63 68 20 63 61 6e 20 6d 61 6b 65  , which can make
197b0 20 73 6f 6d 65 20 71 75 65 72 69 65 73 0a 2a 2a   some queries.**
197c0 20 73 6c 6f 77 65 72 2e 20 20 42 75 74 20 74 68   slower.  But th
197d0 65 20 51 50 53 47 20 68 61 73 20 74 68 65 20 61  e QPSG has the a
197e0 64 76 61 6e 74 61 67 65 20 6f 66 20 6d 6f 72 65  dvantage of more
197f0 20 70 72 65 64 69 63 74 61 62 6c 65 20 62 65 68   predictable beh
19800 61 76 69 6f 72 2e 20 20 57 69 74 68 0a 2a 2a 20  avior.  With.** 
19810 74 68 65 20 51 50 53 47 20 61 63 74 69 76 65 2c  the QPSG active,
19820 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
19830 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d 65  ays use the same
19840 20 71 75 65 72 79 20 70 6c 61 6e 20 69 6e 20 74   query plan in t
19850 68 65 20 66 69 65 6c 64 20 61 73 0a 2a 2a 20 77  he field as.** w
19860 61 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  as used during t
19870 65 73 74 69 6e 67 20 69 6e 20 74 68 65 20 6c 61  esting in the la
19880 62 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c  b..** </dd>.** <
19890 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
198a0 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 3c 2f  IG_TRIGGER_EQP</
198b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79 20 64  dt>.** <dd> By d
198c0 65 66 61 75 6c 74 2c 20 74 68 65 20 6f 75 74 70  efault, the outp
198d0 75 74 20 6f 66 20 45 58 50 4c 41 49 4e 20 51 55  ut of EXPLAIN QU
198e0 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61 6e 64  ERY PLAN command
198f0 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a 20 69  s does not .** i
19900 6e 63 6c 75 64 65 20 6f 75 74 70 75 74 20 66 6f  nclude output fo
19910 72 20 61 6e 79 20 6f 70 65 72 61 74 69 6f 6e 73  r any operations
19920 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 72   performed by tr
19930 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20  igger programs. 
19940 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69  This.** option i
19950 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
19960 20 63 6c 65 61 72 20 28 74 68 65 20 64 65 66 61   clear (the defa
19970 75 6c 74 29 20 61 20 66 6c 61 67 20 74 68 61 74  ult) a flag that
19980 20 67 6f 76 65 72 6e 73 20 74 68 69 73 0a 2a 2a   governs this.**
19990 20 62 65 68 61 76 69 6f 72 2e 20 54 68 65 20 66   behavior. The f
199a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70  irst parameter p
199b0 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70  assed to this op
199c0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 69 6e  eration is an in
199d0 74 65 67 65 72 20 2d 0a 2a 2a 20 6e 6f 6e 2d 7a  teger -.** non-z
199e0 65 72 6f 20 74 6f 20 65 6e 61 62 6c 65 20 6f 75  ero to enable ou
199f0 74 70 75 74 20 66 6f 72 20 74 72 69 67 67 65 72  tput for trigger
19a00 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20 7a 65   programs, or ze
19a10 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 69 74  ro to disable it
19a20 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
19a30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
19a40 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
19a50 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20  eger into which 
19a60 69 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20 30  is written .** 0
19a70 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19a80 65 20 77 68 65 74 68 65 72 20 6f 75 74 70 75 74  e whether output
19a90 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 20 68 61  -for-triggers ha
19aa0 73 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20  s been disabled 
19ab0 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 20 69 73  - 0 if .** it is
19ac0 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
19ad0 20 69 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a 20   if it is.  .** 
19ae0 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  </dd>.** </dl>.*
19af0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19b00 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42  _DBCONFIG_MAINDB
19b10 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
19b20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 68  1000 /* const ch
19b30 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ar* */.#define S
19b40 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
19b50 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 20  OOKASIDE        
19b60 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 69       1001 /* voi
19b70 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
19b80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
19b90 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
19ba0 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30 32  Y           1002
19bb0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
19bc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19bd0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
19be0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31 30  RIGGER        10
19bf0 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  03 /* int int* *
19c00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19c10 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19c20 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 20  _FTS3_TOKENIZER 
19c30 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1004 /* int int*
19c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19c50 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19c60 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f  LE_LOAD_EXTENSIO
19c70 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 6e  N 1005 /* int in
19c80 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
19c90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f  LITE_DBCONFIG_NO
19ca0 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 20  _CKPT_ON_CLOSE  
19cb0 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 20      1006 /* int 
19cc0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
19cd0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19ce0 45 4e 41 42 4c 45 5f 51 50 53 47 20 20 20 20 20  ENABLE_QPSG     
19cf0 20 20 20 20 20 20 31 30 30 37 20 2f 2a 20 69 6e        1007 /* in
19d00 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
19d10 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
19d20 47 5f 54 52 49 47 47 45 52 5f 45 51 50 20 20 20  G_TRIGGER_EQP   
19d30 20 20 20 20 20 20 20 20 31 30 30 38 20 2f 2a 20          1008 /* 
19d40 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
19d50 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
19d60 46 49 47 5f 4d 41 58 20 20 20 20 20 20 20 20 20  FIG_MAX         
19d70 20 20 20 20 20 20 20 20 20 20 31 30 30 38 20 2f            1008 /
19d80 2a 20 4c 61 72 67 65 73 74 20 44 42 43 4f 4e 46  * Largest DBCONF
19d90 49 47 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  IG */../*.** CAP
19da0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
19db0 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65   Disable Extende
19dc0 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
19dd0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
19de0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
19df0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
19e00 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
19e10 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
19e20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
19e30 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
19e40 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
19e50 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
19e60 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
19e70 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
19e80 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
19e90 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
19ea0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
19eb0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
19ec0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
19ed0 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
19ee0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
19ef0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
19f00 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20  Insert Rowid.** 
19f10 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
19f20 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
19f30 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65  y in most SQLite
19f40 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20   tables (except 
19f50 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  for [WITHOUT ROW
19f60 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68  ID] tables).** h
19f70 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
19f80 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
19f90 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
19fa0 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
19fb0 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
19fc0 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
19fd0 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
19fe0 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
19ff0 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
1a000 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
1a010 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
1a020 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
1a030 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
1a040 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
1a050 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
1a060 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
1a070 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
1a080 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
1a090 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
1a0a0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
1a0b0 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
1a0c0 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
1a0d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73  ^The sqlite3_las
1a0e0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
1a0f0 29 20 69 6e 74 65 72 66 61 63 65 20 75 73 75 61  ) interface usua
1a100 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
1a110 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20 74 68  [rowid] of.** th
1a120 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  e most recent su
1a130 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
1a140 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
1a150 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
1a160 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
1a170 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a180 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 20 69 6e  n D. ^Inserts in
1a190 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  to [WITHOUT ROWI
1a1a0 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f  D] tables are no
1a1b0 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e 20 5e  t.** recorded. ^
1a1c0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
1a1d0 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20   [INSERT]s into 
1a1e0 72 6f 77 69 64 20 74 61 62 6c 65 73 20 68 61 76  rowid tables hav
1a1f0 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
1a200 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74 61 62  .** on the datab
1a210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
1a220 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c  , then sqlite3_l
1a230 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a240 28 44 29 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  (D) returns .** 
1a250 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77  zero..**.** As w
1a260 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 73 65 74  ell as being set
1a270 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61   automatically a
1a280 73 20 72 6f 77 73 20 61 72 65 20 69 6e 73 65 72  s rows are inser
1a290 74 65 64 20 69 6e 74 6f 20 64 61 74 61 62 61 73  ted into databas
1a2a0 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74 68 65  e.** tables, the
1a2b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a2c0 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
1a2d0 20 6d 61 79 20 62 65 20 73 65 74 20 65 78 70 6c   may be set expl
1a2e0 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b 73 71  icitly by.** [sq
1a2f0 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
1a300 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
1a310 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74 75 61  *.** Some virtua
1a320 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
1a330 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e 53 45  tations may INSE
1a340 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 72 6f 77  RT rows into row
1a350 69 64 20 74 61 62 6c 65 73 20 61 73 0a 2a 2a 20  id tables as.** 
1a360 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74 74 69  part of committi
1a370 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
1a380 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73 68 20   (e.g. to flush 
1a390 64 61 74 61 20 61 63 63 75 6d 75 6c 61 74 65 64  data accumulated
1a3a0 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74 6f   in memory.** to
1a3b0 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 69 73 20   disk). In this 
1a3c0 63 61 73 65 20 73 75 62 73 65 71 75 65 6e 74 20  case subsequent 
1a3d0 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 20 66 75  calls to this fu
1a3e0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 74 68  nction return th
1a3f0 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73 6f 63  e rowid.** assoc
1a400 69 61 74 65 64 20 77 69 74 68 20 74 68 65 73 65  iated with these
1a410 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45 52 54   internal INSERT
1a420 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68 69   operations, whi
1a430 63 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a 2a 20  ch leads to .** 
1a440 75 6e 69 6e 74 75 69 74 69 76 65 20 72 65 73 75  unintuitive resu
1a450 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 74 61 62  lts. Virtual tab
1a460 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
1a470 6e 73 20 74 68 61 74 20 64 6f 20 77 72 69 74 65  ns that do write
1a480 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74 61 62   to rowid.** tab
1a490 6c 65 73 20 69 6e 20 74 68 69 73 20 77 61 79 20  les in this way 
1a4a0 63 61 6e 20 61 76 6f 69 64 20 74 68 69 73 20 70  can avoid this p
1a4b0 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 74 6f 72  roblem by restor
1a4c0 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ing the original
1a4d0 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c 75 65   .** rowid value
1a4e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1a4f0 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  set_last_insert_
1a500 72 6f 77 69 64 28 29 5d 20 62 65 66 6f 72 65 20  rowid()] before 
1a510 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20 63 6f  returning .** co
1a520 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 75 73 65  ntrol to the use
1a530 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  r..**.** ^(If an
1a540 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
1a550 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
1a560 72 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  r then this rout
1a570 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72 65 74  ine will .** ret
1a580 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
1a590 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 20  of the inserted 
1a5a0 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
1a5b0 68 65 20 74 72 69 67 67 65 72 20 69 73 20 0a 2a  he trigger is .*
1a5c0 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65 20  * running. Once 
1a5d0 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67  the trigger prog
1a5e0 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 20 76 61  ram ends, the va
1a5f0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
1a600 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
1a610 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
1a620 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
1a630 68 65 20 74 72 69 67 67 65 72 20 77 61 73 20 66  he trigger was f
1a640 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41  ired.)^.**.** ^A
1a650 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20  n [INSERT] that 
1a660 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
1a670 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
1a680 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
1a690 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
1a6a0 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  RT] and does not
1a6b0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
1a6c0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
1a6d0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
1a6e0 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20  ^Thus INSERT OR 
1a6f0 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
1a700 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
1a710 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
1a720 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
1a730 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
1a740 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
1a750 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
1a760 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
1a770 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
1a780 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e  ails.  ^(When IN
1a790 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
1a7a0 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
1a7b0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
1a7c0 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
1a7d0 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
1a7e0 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
1a7f0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
1a800 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
1a810 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
1a820 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
1a830 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
1a840 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
1a850 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
1a860 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
1a870 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
1a880 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erface.)^.**.** 
1a890 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
1a8a0 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
1a8b0 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
1a8c0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
1a8d0 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
1a8e0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
1a8f0 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
1a900 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
1a910 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
1a920 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51  accessible to SQ
1a930 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61  L statements via
1a940 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e   the.** [last_in
1a950 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c  sert_rowid() SQL
1a960 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1a970 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1a980 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
1a990 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f  a new [INSERT] o
1a9a0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61  n the same.** da
1a9b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a9c0 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
1a9d0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
1a9e0 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e  _rowid()].** fun
1a9f0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
1aa00 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
1aa10 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
1aa20 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68  t [rowid],.** th
1aa30 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
1aa40 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1aa50 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1aa60 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70  wid()] is.** unp
1aa70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
1aa80 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
1aa90 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
1aaa0 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74   the new.** last
1aab0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
1aac0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  .*/.sqlite3_int6
1aad0 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
1aae0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
1aaf0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1ab00 50 49 33 52 45 46 3a 20 53 65 74 20 74 68 65 20  PI3REF: Set the 
1ab10 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
1ab20 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45 54 48  d value..** METH
1ab30 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1ab40 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65  * The sqlite3_se
1ab50 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  t_last_insert_ro
1ab60 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68 6f 64  wid(D, R) method
1ab70 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70 70 6c   allows the appl
1ab80 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 73 65  ication to.** se
1ab90 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
1aba0 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  rned by calling 
1abb0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
1abc0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74 6f 20  ert_rowid(D) to 
1abd0 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20 69 6e  R .** without in
1abe0 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20 69 6e  serting a row in
1abf0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  to the database.
1ac00 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1ac10 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
1ac20 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 2c  _rowid(sqlite3*,
1ac30 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
1ac40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ac50 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
1ac60 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
1ac70 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
1ac80 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1ac90 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1aca0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1acb0 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20   rows modified, 
1acc0 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64  inserted or.** d
1acd0 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
1ace0 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
1acf0 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
1ad00 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a  DATE or DELETE.*
1ad10 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74  * statement on t
1ad20 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1ad30 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64  ection specified
1ad40 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   by the only par
1ad50 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63  ameter..** ^Exec
1ad60 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
1ad70 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
1ad80 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d  ement does not m
1ad90 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a  odify the value.
1ada0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ** returned by t
1adb0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
1adc0 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65  .** ^Only change
1add0 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20  s made directly 
1ade0 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55  by the INSERT, U
1adf0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
1ae00 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a  statement are.**
1ae10 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75   considered - au
1ae20 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
1ae30 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54  caused by [CREAT
1ae40 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
1ae50 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65  gers], .** [fore
1ae60 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
1ae70 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   or [REPLACE] co
1ae80 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
1ae90 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ion are not coun
1aea0 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e  ted..** .** Chan
1aeb0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
1aec0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
1aed0 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45  ed by .** [INSTE
1aee0 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20  AD OF trigger | 
1aef0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1af00 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ers] are not cou
1af10 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65  nted. ^The value
1af20 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79   .** returned by
1af30 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1af40 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  () immediately a
1af50 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20  fter an INSERT, 
1af60 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45  UPDATE or .** DE
1af70 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72  LETE statement r
1af80 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20  un on a view is 
1af90 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c  always zero. Onl
1afa0 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74  y changes made t
1afb0 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65  o real .** table
1afc0 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
1afd0 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20  *.** Things are 
1afe0 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64  more complicated
1aff0 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   if the sqlite3_
1b000 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
1b010 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65  on is.** execute
1b020 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65  d while a trigge
1b030 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e  r program is run
1b040 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68  ning. This may h
1b050 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20  appen if the.** 
1b060 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65  program uses the
1b070 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
1b080 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66  function], or if
1b090 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c   some other call
1b0a0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
1b0b0 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33   invokes sqlite3
1b0c0 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63  _changes() direc
1b0d0 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79  tly. Essentially
1b0e0 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  :.** .** <ul>.**
1b0f0 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65     <li> ^(Before
1b100 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67   entering a trig
1b110 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20  ger program the 
1b120 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1b130 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69  y.**        sqli
1b140 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
1b150 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e  nction is saved.
1b160 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67   After the trigg
1b170 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20  er program .**  
1b180 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68        has finish
1b190 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ed, the original
1b1a0 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72   value is restor
1b1b0 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c  ed.)^.** .**   <
1b1c0 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74  li> ^(Within a t
1b1d0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65  rigger program e
1b1e0 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ach INSERT, UPDA
1b1f0 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a  TE and DELETE .*
1b200 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65  *        stateme
1b210 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75  nt sets the valu
1b220 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
1b230 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1b240 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20  .**        upon 
1b250 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f  completion as no
1b260 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c  rmal. Of course,
1b270 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c   this value will
1b280 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a   not include .**
1b290 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e          any chan
1b2a0 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79  ges performed by
1b2b0 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61   sub-triggers, a
1b2c0 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  s the sqlite3_ch
1b2d0 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
1b2e0 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65     value will be
1b2f0 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f   saved and resto
1b300 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73  red after each s
1b310 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72  ub-trigger has r
1b320 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  un.)^.** </ul>.*
1b330 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e  * .** ^This mean
1b340 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68  s that if the ch
1b350 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1b360 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72  tion (or similar
1b370 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20  ) is used.** by 
1b380 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54  the first INSERT
1b390 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1b3a0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
1b3b0 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69  hin a trigger, i
1b3c0 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  t .** returns th
1b3d0 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77  e value as set w
1b3e0 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  hen the calling 
1b3f0 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20  statement began 
1b400 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49  executing..** ^I
1b410 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20  f it is used by 
1b420 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75  the second or su
1b430 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74  bsequent such st
1b440 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
1b450 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f   trigger .** pro
1b460 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20  gram, the value 
1b470 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74  returned reflect
1b480 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1b490 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79  rows modified by
1b4a0 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75   the .** previou
1b4b0 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  s INSERT, UPDATE
1b4c0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
1b4d0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
1b4e0 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
1b4f0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
1b500 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
1b510 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
1b520 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
1b530 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
1b540 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68  ma], and the [ch
1b550 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1b560 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1b570 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1b580 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
1b590 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
1b5a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1b5b0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
1b5c0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
1b5d0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
1b5e0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1b5f0 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
1b600 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
1b610 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
1b620 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
1b630 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1b640 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
1b650 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
1b660 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
1b670 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1b680 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1b690 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74   returns the tot
1b6a0 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  al number of row
1b6b0 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69  s inserted, modi
1b6c0 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  fied or.** delet
1b6d0 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52  ed by all [INSER
1b6e0 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  T], [UPDATE] or 
1b6f0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
1b700 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a  nts completed.**
1b710 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
1b720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
1b730 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75  as opened, inclu
1b740 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75  ding those execu
1b750 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ted as.** part o
1b760 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  f trigger progra
1b770 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61  ms. ^Executing a
1b780 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
1b790 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
1b7a0 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63  * does not affec
1b7b0 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
1b7c0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1b7d0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e  total_changes().
1b7e0 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  .** .** ^Changes
1b7f0 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
1b800 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
1b810 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75  tions] are inclu
1b820 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f  ded in the.** co
1b830 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d  unt, but those m
1b840 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52  ade as part of R
1b850 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
1b860 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
1b870 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65  .** not. ^Change
1b880 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
1b890 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
1b8a0 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74   by INSTEAD OF t
1b8b0 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20  riggers .** are 
1b8c0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
1b8d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
1b8e0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
1b8f0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
1b900 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
1b910 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
1b920 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
1b930 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1b940 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1b950 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1b960 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
1b970 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
1b980 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1b990 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
1b9a0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1b9b0 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1b9c0 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
1b9d0 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
1b9e0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1b9f0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
1ba00 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74  .int sqlite3_tot
1ba10 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
1ba20 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1ba30 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
1ba40 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
1ba50 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Query.** METHOD:
1ba60 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1ba70 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61  This function ca
1ba80 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67  uses any pending
1ba90 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
1baa0 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64  ion to abort and
1bab0 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74  .** return at it
1bac0 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72  s earliest oppor
1bad0 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75  tunity. This rou
1bae0 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c  tine is typicall
1baf0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72  y.** called in r
1bb00 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65  esponse to a use
1bb10 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73  r action such as
1bb20 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65   pressing "Cance
1bb30 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20  l".** or Ctrl-C 
1bb40 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77  where the user w
1bb50 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72  ants a long quer
1bb60 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68  y operation to h
1bb70 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65  alt.** immediate
1bb80 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ly..**.** ^It is
1bb90 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
1bba0 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20  is routine from 
1bbb0 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65  a thread differe
1bbc0 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74  nt from the.** t
1bbd0 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75  hread that is cu
1bbe0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20  rrently running 
1bbf0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65  the database ope
1bc00 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a  ration.  But it.
1bc10 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  ** is not safe t
1bc20 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
1bc30 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61  ine with a [data
1bc40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1bc50 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73   that.** is clos
1bc60 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73  ed or might clos
1bc70 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  e before sqlite3
1bc80 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74  _interrupt() ret
1bc90 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  urns..**.** ^If 
1bca0 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  an SQL operation
1bcb0 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20   is very nearly 
1bcc0 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20  finished at the 
1bcd0 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c  time when.** sql
1bce0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1bcf0 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e   is called, then
1bd00 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61   it might not ha
1bd10 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74  ve an opportunit
1bd20 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72  y.** to be inter
1bd30 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74  rupted and might
1bd40 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d   continue to com
1bd50 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  pletion..**.** ^
1bd60 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  An SQL operation
1bd70 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75   that is interru
1bd80 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e  pted will return
1bd90 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
1bda0 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  PT]..** ^If the 
1bdb0 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20  interrupted SQL 
1bdc0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20  operation is an 
1bdd0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
1bde0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
1bdf0 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65  t is inside an e
1be00 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
1be10 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e  ion, then the en
1be20 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  tire transaction
1be30 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c  .** will be roll
1be40 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69  ed back automati
1be50 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  cally..**.** ^Th
1be60 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1be70 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69  upt(D) call is i
1be80 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61  n effect until a
1be90 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  ll currently run
1bea0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
1beb0 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62  ements on [datab
1bec0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1bed0 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e  D complete.  ^An
1bee0 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d  y new SQL statem
1bef0 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1bf00 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1bf10 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1bf20 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20  rupt() call and 
1bf30 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72  before the .** r
1bf40 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
1bf50 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  s reaches zero a
1bf60 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  re interrupted a
1bf70 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65  s if they had be
1bf80 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72  en.** running pr
1bf90 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ior to the sqlit
1bfa0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
1bfb0 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73  all.  ^New SQL s
1bfc0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1bfd0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1bfe0 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
1bff0 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
1c000 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
1c010 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
1c020 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
1c030 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
1c040 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ^A call to sqlit
1c050 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20  e3_interrupt(D) 
1c060 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e  that occurs when
1c070 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75   there are no ru
1c080 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
1c090 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d  tements is a no-
1c0a0 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66  op and has no ef
1c0b0 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74  fect on SQL stat
1c0c0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1c0d0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1c0e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1c0f0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65  errupt() call re
1c100 74 75 72 6e 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73  turns..*/.void s
1c110 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1c120 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1c130 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
1c140 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
1c150 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
1c160 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
1c170 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1c180 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
1c190 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
1c1a0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
1c1b0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
1c1c0 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
1c1d0 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
1c1e0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
1c1f0 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
1c200 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
1c210 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
1c220 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
1c230 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
1c240 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
1c250 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1c260 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
1c270 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
1c280 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
1c290 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
1c2a0 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
1c2b0 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
1c2c0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
1c2d0 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
1c2e0 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
1c2f0 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
1c300 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
1c310 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
1c320 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
1c330 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
1c340 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
1c350 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
1c360 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
1c370 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
1c380 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
1c390 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
1c3a0 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
1c3b0 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
1c3c0 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
1c3d0 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
1c3e0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
1c3f0 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
1c400 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
1c410 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
1c420 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
1c430 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
1c440 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
1c450 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
1c460 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
1c470 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1c480 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
1c490 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
1c4a0 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
1c4b0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
1c4c0 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
1c4d0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
1c4e0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1c4f0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1c500 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
1c510 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1c520 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
1c530 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
1c540 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
1c550 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
1c560 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
1c570 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
1c580 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
1c590 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
1c5a0 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
1c5b0 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
1c5c0 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
1c5d0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
1c5e0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
1c5f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
1c600 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1c610 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
1c620 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
1c630 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
1c640 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1c650 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
1c660 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
1c670 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
1c680 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1c690 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
1c6a0 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
1c6b0 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
1c6c0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1c6d0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
1c6e0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1c6f0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1c700 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
1c710 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1c720 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1c730 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1c740 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1c750 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
1c760 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
1c770 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  der..*/.int sqli
1c780 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
1c790 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69  st char *sql);.i
1c7a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
1c7b0 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
1c7c0 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
1c7d0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
1c7e0 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
1c7f0 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
1c800 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59  SY Errors.** KEY
1c810 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e  WORDS: {busy-han
1c820 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b  dler callback} {
1c830 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a  busy handler}.**
1c840 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1c850 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c860 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1c870 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20  (D,X,P) routine 
1c880 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
1c890 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68  function X.** th
1c8a0 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
1c8b0 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ked with argumen
1c8c0 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  t P whenever.** 
1c8d0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
1c8e0 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64  de to access a d
1c8f0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73  atabase table as
1c900 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
1c910 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c920 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e  ction] D when an
1c930 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
1c940 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74  or process has t
1c950 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e  he table locked.
1c960 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1c970 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69  busy_handler() i
1c980 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
1c990 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a   to implement.**
1c9a0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1c9b0 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50  imeout()] and [P
1c9c0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1c9d0 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ut]..**.** ^If t
1c9e0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1c9f0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
1ca00 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1ca10 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
1ca20 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
1ca30 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
1ca40 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
1ca50 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
1ca60 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
1ca70 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
1ca80 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1ca90 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
1caa0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1cab0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1cac0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1cad0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1cae0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
1caf0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
1cb00 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
1cb10 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1cb20 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
1cb30 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
1cb40 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
1cb50 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
1cb60 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1cb70 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
1cb80 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
1cb90 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
1cba0 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74  previously for t
1cbb0 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20  he same locking 
1cbc0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
1cbd0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
1cbe0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
1cbf0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
1cc00 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
1cc10 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
1cc20 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
1cc30 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20  SQLITE_BUSY] is 
1cc40 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74  returned.** to t
1cc50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a  he application..
1cc60 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
1cc70 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1cc80 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
1cc90 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
1cca0 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
1ccb0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1ccc0 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
1ccd0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
1cce0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
1ccf0 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
1cd00 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
1cd10 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
1cd20 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
1cd30 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
1cd40 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
1cd50 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
1cd60 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
1cd70 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
1cd80 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
1cd90 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
1cda0 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
1cdb0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
1cdc0 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  SY].** to the ap
1cdd0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61  plication instea
1cde0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
1cdf0 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  e .** busy handl
1ce00 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
1ce10 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
1ce20 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
1ce30 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
1ce40 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
1ce50 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
1ce60 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
1ce70 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
1ce80 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
1ce90 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
1cea0 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
1ceb0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
1cec0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
1ced0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
1cee0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
1cef0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
1cf00 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
1cf10 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1cf20 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
1cf30 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1cf40 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
1cf50 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
1cf60 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
1cf70 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
1cf80 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
1cf90 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
1cfa0 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
1cfb0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
1cfc0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
1cfd0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
1cfe0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
1cff0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
1d000 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
1d010 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
1d020 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
1d030 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
1d040 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
1d050 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
1d060 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1d070 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
1d080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1d090 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
1d0a0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1d0b0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1d0c0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1d0d0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
1d0e0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
1d0f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d100 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
1d110 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
1d120 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
1d130 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
1d140 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
1d150 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
1d160 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1d170 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c  ut()].** or eval
1d180 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62  uating [PRAGMA b
1d190 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77  usy_timeout=N] w
1d1a0 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a  ill change the.*
1d1b0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61  * busy handler a
1d1c0 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e  nd thus clear an
1d1d0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  y previously set
1d1e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1d1f0 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
1d200 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
1d210 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
1d220 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
1d230 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1d240 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1d250 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1d260 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74   handler.  In ot
1d270 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68  her words,.** th
1d280 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
1d290 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  s not reentrant.
1d2a0 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
1d2b0 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
1d2c0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
1d2d0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
1d2e0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
1d2f0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
1d300 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d310 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
1d320 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1d330 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1d340 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
1d350 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
1d360 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1d370 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
1d380 29 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ),void*);../*.**
1d390 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
1d3a0 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
1d3b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1d3c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1d3d0 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
1d3e0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1d3f0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
1d400 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
1d410 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
1d420 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
1d430 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
1d440 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
1d450 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
1d460 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
1d470 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
1d480 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1d490 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
1d4a0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
1d4b0 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
1d4c0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1d4d0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1d4e0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
1d4f0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
1d500 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
1d510 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
1d520 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
1d530 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  _BUSY]..**.** ^C
1d540 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
1d550 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
1d560 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
1d570 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
1d580 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
1d590 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
1d5a0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1d5b0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1d5c0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1d5d0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
1d5e0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1d5f0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79  nnection] at any
1d600 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
1d610 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
1d620 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
1d630 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
1d640 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1d650 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
1d660 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
1d670 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
1d680 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1d690 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
1d6a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1d6b0 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74    [PRAGMA busy_t
1d6c0 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73  imeout].*/.int s
1d6d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1d6e0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
1d6f0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
1d700 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
1d710 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
1d720 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
1d730 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1d740 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te3.**.** This i
1d750 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
1d760 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
1d770 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
1d780 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1d790 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
1d7a0 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1d7b0 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
1d7c0 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
1d7d0 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
1d7e0 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
1d7f0 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
1d800 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
1d810 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1d820 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
1d830 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
1d840 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
1d850 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
1d860 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
1d870 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
1d880 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
1d890 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
1d8a0 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
1d8b0 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
1d8c0 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
1d8d0 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
1d8e0 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
1d8f0 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
1d900 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
1d910 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
1d920 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1d930 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1d940 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1d950 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1d960 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1d970 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1d980 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1d990 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1d9a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1d9b0 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1d9c0 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1d9d0 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1d9e0 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1d9f0 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1da00 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1da10 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1da20 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1da30 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1da40 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1da50 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1da60 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1da70 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1da80 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1da90 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1daa0 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1dab0 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1dac0 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1dad0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1dae0 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1daf0 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1db00 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1db10 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1db20 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1db30 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1db40 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1db50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1db60 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1db70 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1db80 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1db90 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1dba0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1dbb0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1dbc0 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1dbd0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1dbe0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1dbf0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1dc00 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1dc10 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1dc20 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1dc30 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1dc40 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1dc50 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1dc60 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1dc70 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1dc80 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1dc90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1dca0 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1dcb0 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1dcc0 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1dcd0 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1dce0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1dcf0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1dd00 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1dd10 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1dd20 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1dd30 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1dd40 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1dd50 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1dd60 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1dd70 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1dd80 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1dd90 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1dda0 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1ddb0 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1ddc0 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1ddd0 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1dde0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1ddf0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1de00 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1de10 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1de20 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1de30 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1de40 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1de50 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1de60 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1de70 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1de80 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1de90 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1dea0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1deb0 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1dec0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1ded0 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1dee0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1def0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1df00 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1df10 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1df20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1df30 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1df40 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1df50 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1df60 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1df70 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1df80 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1df90 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1dfa0 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1dfb0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1dfc0 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1dfd0 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1dfe0 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1dff0 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1e000 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1e010 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1e020 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1e030 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1e040 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1e050 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1e060 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1e070 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1e080 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1e090 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1e0a0 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1e0b0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1e0c0 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1e0d0 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1e0e0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1e0f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1e100 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1e110 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1e120 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1e130 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1e140 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1e150 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1e160 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1e170 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1e180 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1e190 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1e1a0 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1e1b0 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1e1c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1e1d0 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1e1e0 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1e1f0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1e200 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1e210 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1e220 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1e230 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1e240 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1e250 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1e260 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1e270 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1e280 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1e290 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1e2a0 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1e2b0 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1e2c0 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1e2d0 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1e2e0 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1e2f0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1e300 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1e310 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1e320 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1e330 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1e340 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1e350 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1e360 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1e370 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  rrmsg()]..*/.int
1e380 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1e390 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
1e3a0 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
1e3b0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
1e3c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1e3d0 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
1e3e0 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
1e3f0 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
1e400 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
1e410 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
1e420 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
1e430 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
1e440 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1e450 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
1e460 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
1e470 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
1e480 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1e490 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
1e4a0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
1e4b0 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
1e4c0 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
1e4d0 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
1e4e0 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
1e4f0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
1e500 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
1e510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
1e520 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
1e530 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
1e540 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1e550 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
1e560 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
1e570 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
1e580 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
1e590 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
1e5a0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
1e5b0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75  These routines u
1e5c0 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f  nderstand most o
1e5d0 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52  f the common K&R
1e5e0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1e5f0 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d  ons,.** plus som
1e600 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e  e additional non
1e610 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74  -standard format
1e620 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f  s, detailed belo
1e630 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  w..** Note that 
1e640 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65  some of the more
1e650 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74   obscure formatt
1e660 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d  ing options from
1e670 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62   recent.** C-lib
1e680 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 20 61  rary standards a
1e690 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  re omitted from 
1e6a0 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  this implementat
1e6b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
1e6c0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1e6d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
1e6e0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1e6f0 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
1e700 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
1e710 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
1e720 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
1e730 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
1e740 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1e750 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
1e760 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
1e770 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
1e780 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
1e790 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
1e7a0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
1e7b0 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
1e7c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
1e7d0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
1e7e0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
1e7f0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1e800 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
1e810 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ng..**.** ^(The 
1e820 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1e830 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
1e840 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
1e850 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
1e860 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1e870 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
1e880 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
1e890 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
1e8a0 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
1e8b0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1e8c0 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
1e8d0 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
1e8e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
1e8f0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
1e900 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
1e910 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
1e920 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
1e930 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
1e940 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
1e950 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
1e960 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
1e970 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
1e980 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
1e990 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1e9a0 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
1e9b0 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
1e9c0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
1e9d0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1e9e0 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
1e9f0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
1ea00 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
1ea10 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
1ea20 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
1ea30 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
1ea40 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
1ea50 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
1ea60 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
1ea70 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
1ea80 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
1ea90 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
1eaa0 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
1eab0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
1eac0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1ead0 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
1eae0 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
1eaf0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
1eb00 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
1eb10 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
1eb20 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
1eb30 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1eb40 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
1eb50 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
1eb60 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
1eb70 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
1eb80 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1eb90 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
1eba0 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
1ebb0 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
1ebc0 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
1ebd0 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
1ebe0 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
1ebf0 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
1ec00 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
1ec10 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
1ec20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
1ec30 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  acters..**.** ^T
1ec40 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  he sqlite3_vsnpr
1ec50 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1ec60 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73  s a varargs vers
1ec70 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1ec80 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a  nprintf()..**.**
1ec90 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1eca0 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
1ecb0 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
1ecc0 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
1ecd0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
1ece0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
1ecf0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
1ed00 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
1ed10 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
1ed20 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
1ed30 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
1ed40 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
1ed50 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
1ed60 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22  "%Q", "%w" and "
1ed70 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1ed80 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1ed90 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1eda0 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1edb0 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
1edc0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1edd0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
1ede0 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
1edf0 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
1ee00 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
1ee10 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
1ee20 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
1ee30 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
1ee40 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
1ee50 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
1ee60 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
1ee70 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
1ee80 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
1ee90 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
1eea0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
1eeb0 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
1eec0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
1eed0 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
1eee0 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
1eef0 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
1ef00 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1ef10 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1ef20 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
1ef30 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
1ef40 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
1ef50 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1ef60 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
1ef70 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
1ef80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1ef90 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1efa0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1efb0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1efc0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1efd0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1efe0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
1eff0 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
1f000 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1f010 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1f020 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1f030 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1f040 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1f050 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1f060 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
1f070 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1f080 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
1f090 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
1f0a0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
1f0b0 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
1f0c0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1f0d0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1f0e0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1f0f0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1f100 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
1f110 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
1f120 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1f130 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
1f140 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
1f150 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
1f160 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
1f170 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
1f180 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
1f190 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
1f1a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1f1b0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1f1c0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1f1d0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1f1e0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1f1f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1f200 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
1f210 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
1f220 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
1f230 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
1f240 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
1f250 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
1f260 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
1f270 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
1f280 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1f290 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
1f2a0 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
1f2b0 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
1f2c0 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
1f2d0 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
1f2e0 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
1f2f0 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
1f300 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1f310 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
1f320 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
1f330 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
1f340 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1f350 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
1f360 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
1f370 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
1f380 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
1f390 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
1f3a0 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
1f3b0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1f3c0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1f3d0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1f3e0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1f3f0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1f400 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
1f410 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1f420 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1f430 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1f440 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1f450 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1f460 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
1f470 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
1f480 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
1f490 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
1f4a0 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
1f4b0 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
1f4c0 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
1f4d0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1f4e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1f4f0 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
1f500 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71  tion is like "%q
1f510 22 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  " except that it
1f520 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62   expects to.** b
1f530 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68  e contained with
1f540 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73  in double-quotes
1f550 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67   instead of sing
1f560 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69  le quotes, and i
1f570 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65  t.** escapes the
1f580 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68   double-quote ch
1f590 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 64 20  aracter instead 
1f5a0 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75  of the single-qu
1f5b0 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  ote.** character
1f5c0 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f  .)^  The "%w" fo
1f5d0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1f5e0 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
1f5f0 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67  safely inserting
1f600 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  .** table and co
1f610 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20  lumn names into 
1f620 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51  a constructed SQ
1f630 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  L statement..**.
1f640 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f  ** ^(The "%z" fo
1f650 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1f660 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20  works like "%s" 
1f670 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  but with the.** 
1f680 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
1f690 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
1f6a0 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
1f6b0 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
1f6c0 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
1f6d0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
1f6e0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
1f6f0 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f  put string.)^.*/
1f700 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d  .char *sqlite3_m
1f710 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1f720 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  r*,...);.char *s
1f730 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1f740 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1f750 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  list);.char *sql
1f760 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
1f770 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1f780 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20  ar*, ...);.char 
1f790 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e  *sqlite3_vsnprin
1f7a0 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1f7b0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1f7c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1f7d0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1f7e0 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
1f7f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
1f800 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
1f810 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
1f820 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
1f830 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
1f840 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f850 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
1f860 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1f870 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
1f880 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
1f890 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
1f8a0 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
1f8b0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
1f8c0 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
1f8d0 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
1f8e0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
1f8f0 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
1f900 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
1f910 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1f920 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1f930 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
1f940 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
1f950 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
1f960 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
1f970 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
1f980 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73  ameter..** ^If s
1f990 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1f9a0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
1f9b0 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
1f9c0 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
1f9d0 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
1f9e0 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74   pointer.  ^If t
1f9f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
1fa00 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
1fa10 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
1fa20 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
1fa30 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1fa40 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
1fa50 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1fa60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1fa70 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e  lloc64(N) routin
1fa80 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b  e works just lik
1fa90 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  e.** sqlite3_mal
1faa0 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74 68  loc(N) except th
1fab0 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67  at N is an unsig
1fac0 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ned 64-bit integ
1fad0 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
1fae0 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74   a signed 32-bit
1faf0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
1fb00 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
1fb10 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
1fb20 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
1fb30 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
1fb40 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1fb50 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1fb60 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
1fb70 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
1fb80 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
1fb90 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
1fba0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1fbb0 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
1fbc0 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
1fbd0 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1fbe0 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
1fbf0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
1fc00 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
1fc10 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
1fc20 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
1fc30 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
1fc40 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
1fc50 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
1fc60 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
1fc70 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
1fc80 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
1fc90 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
1fca0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1fcb0 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
1fcc0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
1fcd0 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
1fce0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1fcf0 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
1fd00 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
1fd10 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
1fd20 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1fd30 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
1fd40 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
1fd50 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
1fd60 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1fd70 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1fd80 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1fd90 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
1fda0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1fdb0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  ,N) interface at
1fdc0 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
1fdd0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
1fde0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20  ry allocation X 
1fdf0 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
1fe00 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
1fe10 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74  he X parameter t
1fe20 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1fe30 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e  c(X,N).** is a N
1fe40 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1fe50 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
1fe60 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
1fe70 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1fe80 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e  _malloc(N)..** ^
1fe90 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  If the N paramet
1fea0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1feb0 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65  alloc(X,N) is ze
1fec0 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
1fed0 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
1fee0 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
1fef0 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
1ff00 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
1ff10 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  ee(X)..** ^sqlit
1ff20 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1ff30 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1ff40 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
1ff50 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
1ff60 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1ff70 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
1ff80 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20  if insufficient 
1ff90 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61  memory is availa
1ffa0 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73  ble..** ^If M is
1ffb0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
1ffc0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1ffd0 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
1ffe0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
1fff0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
20000 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
20010 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
20020 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
20030 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
20040 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e  _realloc(X,N) an
20050 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
20060 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
20070 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
20080 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
20090 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20  urns NULL and N 
200a0 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65  is positive, the
200b0 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61  n the.** prior a
200c0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74  llocation is not
200d0 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   freed..**.** ^T
200e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
200f0 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66  oc64(X,N) interf
20100 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73  aces works the s
20110 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65  ame as.** sqlite
20120 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65  3_realloc(X,N) e
20130 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
20140 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65  a 64-bit unsigne
20150 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61  d integer instea
20160 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74  d.** of a 32-bit
20170 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e   signed integer.
20180 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20  .**.** ^If X is 
20190 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
201a0 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  ion previously o
201b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
201c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a  ite3_malloc(),.*
201d0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
201e0 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  64(), sqlite3_re
201f0 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69  alloc(), or sqli
20200 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c  te3_realloc64(),
20210 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
20220 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
20230 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
20240 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  at memory alloca
20250 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a  tion in bytes..*
20260 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74  * ^The value ret
20270 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
20280 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20  _msize(X) might 
20290 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
202a0 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20  he number.** of 
202b0 62 79 74 65 73 20 72 65 71 75 65 73 74 65 64 20  bytes requested 
202c0 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63  when X was alloc
202d0 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20  ated.  ^If X is 
202e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
202f0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  hen.** sqlite3_m
20300 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20  size(X) returns 
20310 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e  zero.  If X poin
20320 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20  ts to something 
20330 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74  that is not.** t
20340 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
20350 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
20360 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e  n, or if it poin
20370 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79  ts to a formerly
20380 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79  .** valid memory
20390 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74   allocation that
203a0 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72   has now been fr
203b0 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  eed, then the be
203c0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c  havior.** of sql
203d0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73  ite3_msize(X) is
203e0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
203f0 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e  ossibly harmful.
20400 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
20410 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
20420 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
20430 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
20440 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
20450 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73  alloc64(), and s
20460 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
20470 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
20480 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
20490 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
204a0 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a  undary, or to a.
204b0 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61  ** 4 byte bounda
204c0 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ry if the [SQLIT
204d0 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44  E_4_BYTE_ALIGNED
204e0 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65  _MALLOC] compile
204f0 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
20500 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
20510 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
20520 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
20530 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
20540 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
20550 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
20560 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
20570 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
20580 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
20590 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
205a0 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
205b0 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
205c0 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
205d0 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
205e0 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
205f0 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
20600 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
20610 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
20620 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74  * Prior to SQLit
20630 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30  e version 3.7.10
20640 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  , the Windows OS
20650 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
20660 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73   called.** the s
20670 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
20680 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
20690 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
206a0 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
206b0 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
206c0 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
206d0 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
206e0 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
206f0 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
20700 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
20710 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
20720 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
20730 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
20740 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65  n errors were de
20750 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
20760 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65  hey were reporte
20770 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
20780 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
20790 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
207a0 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
207b0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
207c0 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
207d0 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
207e0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
207f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
20800 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
20810 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
20820 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
20830 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
20840 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
20850 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
20860 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
20870 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
20880 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
20890 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
208a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
208b0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
208c0 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
208d0 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
208e0 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
208f0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
20900 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
20910 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
20920 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
20930 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
20940 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
20950 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
20960 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36  *sqlite3_malloc6
20970 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  4(sqlite3_uint64
20980 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
20990 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
209a0 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
209b0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f  te3_realloc64(vo
209c0 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
209d0 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
209e0 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
209f0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73  sqlite3_uint64 s
20a00 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69  qlite3_msize(voi
20a10 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
20a20 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
20a30 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
20a40 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
20a50 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
20a60 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
20a70 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
20a80 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
20a90 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
20aa0 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
20ab0 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
20ac0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
20ad0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
20ae0 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
20af0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
20b00 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
20b10 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
20b20 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
20b30 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
20b40 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
20b50 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
20b60 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
20b70 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
20b80 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
20b90 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
20ba0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
20bb0 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
20bc0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
20bd0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
20be0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
20bf0 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
20c00 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
20c10 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
20c20 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
20c30 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
20c40 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
20c50 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
20c60 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20c70 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
20c80 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
20c90 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
20ca0 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
20cb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
20cc0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20cd0 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
20ce0 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
20cf0 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
20d00 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
20d10 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
20d20 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
20d30 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
20d40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
20d50 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
20d60 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
20d70 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
20d80 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
20d90 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
20da0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
20db0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
20dc0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20dd0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
20de0 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
20df0 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
20e00 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
20e10 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
20e20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
20e30 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
20e40 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
20e50 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
20e60 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
20e70 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
20e80 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
20e90 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
20ea0 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
20eb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20ec0 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
20ed0 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
20ee0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
20ef0 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
20f00 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
20f10 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
20f20 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
20f30 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
20f40 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
20f50 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
20f60 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
20f70 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
20f80 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
20f90 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
20fa0 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
20fb0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
20fc0 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
20fd0 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
20fe0 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
20ff0 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
21000 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
21010 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
21020 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
21030 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
21040 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
21050 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
21060 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
21070 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
21080 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
21090 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
210a0 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61  ..** ^The P para
210b0 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e  meter can be a N
210c0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
210d0 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74  ** ^If this rout
210e0 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ine has not been
210f0 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c   previously call
21100 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72 65  ed or if the pre
21110 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61  vious.** call ha
21120 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e  d N less than on
21130 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e or a NULL poin
21140 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20  ter for P, then 
21150 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73  the PRNG is.** s
21160 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
21170 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20  omness obtained 
21180 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
21190 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a  ness method of.*
211a0 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  * the default [s
211b0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
211c0 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  ct..** ^If the p
211d0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
211e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64  this routine had
211f0 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f   an N of 1 or mo
21200 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d  re and a.** non-
21210 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20  NULL P then the 
21220 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
21230 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
21240 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
21250 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
21260 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
21270 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
21280 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
21290 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
212a0 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
212b0 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
212c0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
212d0 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
212e0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
212f0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
21300 65 33 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e3.** KEYWORDS: 
21310 7b 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c  {authorizer call
21320 62 61 63 6b 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  back}.**.** ^Thi
21330 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74  s routine regist
21340 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ers an authorize
21350 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20  r callback with 
21360 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
21370 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
21380 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20  tion], supplied 
21390 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
213a0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61  ument..** ^The a
213b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
213c0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  ck is invoked as
213d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
213e0 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c  are being compil
213f0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
21400 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
21410 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71  its variants [sq
21420 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21430 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
21440 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20  _prepare_v3()], 
21450 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21460 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
21470 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
21480 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
21490 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
214a0 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
214b0 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
214c0 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
214d0 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
214e0 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
214f0 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
21500 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
21510 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
21520 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
21530 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
21540 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
21550 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
21560 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
21570 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
21580 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
21590 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
215a0 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
215b0 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
215c0 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
215d0 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
215e0 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
215f0 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
21600 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
21610 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
21620 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
21630 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
21640 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
21650 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
21660 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
21670 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
21680 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
21690 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
216a0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
216b0 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
216c0 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
216d0 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
216e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
216f0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
21700 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
21710 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
21720 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
21730 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
21740 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
21750 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
21760 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
21770 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
21780 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
21790 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
217a0 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
217b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
217c0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
217d0 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
217e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
217f0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
21800 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
21810 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
21820 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
21830 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
21840 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
21850 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
21860 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
21870 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
21880 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
21890 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
218a0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
218b0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
218c0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
218d0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
218e0 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
218f0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
21900 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
21910 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
21920 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
21930 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
21940 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
21950 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
21960 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
21970 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
21980 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
21990 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
219a0 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
219b0 62 61 63 6b 20 61 72 65 20 65 69 74 68 65 72 20  back are either 
219c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6f 72  NULL pointers or
219d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
219e0 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74 68 61 74   strings.** that
219f0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
21a00 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f 75  nal details abou
21a10 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
21a20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
21a30 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d  * Applications m
21a40 75 73 74 20 61 6c 77 61 79 73 20 62 65 20 70 72  ust always be pr
21a50 65 70 61 72 65 64 20 74 6f 20 65 6e 63 6f 75 6e  epared to encoun
21a60 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ter a NULL point
21a70 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20 6f 66 20  er in any.** of 
21a80 74 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  the third throug
21a90 68 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61  h the sixth para
21aa0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 61 75  meters of the au
21ab0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c 6c  thorization call
21ac0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  back..**.** ^If 
21ad0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
21ae0 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
21af0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
21b00 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
21b10 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
21b20 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
21b30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
21b40 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
21b50 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
21b60 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
21b70 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
21b80 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
21b90 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
21ba0 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
21bb0 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
21bc0 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
21bd0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
21be0 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
21bf0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
21c00 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
21c10 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
21c20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
21c30 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
21c40 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 74 61 62  ..** ^When a tab
21c50 6c 65 20 69 73 20 72 65 66 65 72 65 6e 63 65 64  le is referenced
21c60 20 62 79 20 61 20 5b 53 45 4c 45 43 54 5d 20 62   by a [SELECT] b
21c70 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c  ut no column val
21c80 75 65 73 20 61 72 65 0a 2a 2a 20 65 78 74 72 61  ues are.** extra
21c90 63 74 65 64 20 66 72 6f 6d 20 74 68 61 74 20 74  cted from that t
21ca0 61 62 6c 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  able (for exampl
21cb0 65 20 69 6e 20 61 20 71 75 65 72 79 20 6c 69 6b  e in a query lik
21cc0 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20 63 6f 75  e.** "SELECT cou
21cd0 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61 62 22 29  nt(*) FROM tab")
21ce0 20 74 68 65 6e 20 74 68 65 20 5b 53 51 4c 49 54   then the [SQLIT
21cf0 45 5f 52 45 41 44 5d 20 61 75 74 68 6f 72 69 7a  E_READ] authoriz
21d00 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
21d10 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66  s invoked once f
21d20 6f 72 20 74 68 61 74 20 74 61 62 6c 65 20 77 69  or that table wi
21d30 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  th a column name
21d40 20 74 68 61 74 20 69 73 20 61 6e 20 65 6d 70 74   that is an empt
21d50 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  y string..** ^If
21d60 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
21d70 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45   is [SQLITE_DELE
21d80 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  TE] and the call
21d90 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
21da0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
21db0 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45  then the [DELETE
21dc0 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  ] operation proc
21dd0 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20  eeds but the.** 
21de0 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
21df0 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62  zation] is disab
21e00 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73  led and all rows
21e10 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64   are deleted ind
21e20 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  ividually..**.**
21e30 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
21e40 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
21e50 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
21e60 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
21e70 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
21e80 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
21e90 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
21ea0 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
21eb0 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
21ec0 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
21ed0 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
21ee0 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
21ef0 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
21f00 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
21f10 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
21f20 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
21f30 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
21f40 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
21f50 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
21f60 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
21f70 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
21f80 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
21f90 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
21fa0 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
21fb0 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
21fc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
21fd0 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
21fe0 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
21ff0 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
22000 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
22010 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
22020 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
22030 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
22040 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
22050 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
22060 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
22070 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22080 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
22090 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
220a0 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
220b0 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
220c0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
220d0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
220e0 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
220f0 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
22100 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
22110 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
22120 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
22130 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
22140 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
22150 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
22160 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
22170 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
22180 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
22190 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
221a0 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
221b0 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
221c0 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65   ^(Only a single
221d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
221e0 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
221f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22200 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
22210 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
22220 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
22230 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
22240 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
22250 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61  s call.)^  ^Disa
22260 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
22270 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
22280 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
22290 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
222a0 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
222b0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
222c0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
222d0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
222e0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
222f0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
22300 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
22310 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
22320 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
22330 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
22340 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
22350 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22360 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
22370 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
22380 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
22390 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
223a0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
223b0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
223c0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
223d0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b  h..**.** ^When [
223e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
223f0 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
22400 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
22410 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
22420 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
22430 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69  re-prepared duri
22440 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
22450 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
22460 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
22470 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
22480 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
22490 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
224a0 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
224b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
224c0 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
224d0 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
224e0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
224f0 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
22500 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
22510 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
22520 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
22530 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
22540 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
22550 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
22560 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
22570 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
22580 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
22590 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
225a0 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
225b0 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
225c0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
225d0 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
225e0 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
225f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
22600 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
22610 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
22620 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
22630 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ange..*/.int sql
22640 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
22650 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
22660 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
22670 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
22680 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
22690 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
226a0 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
226b0 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
226c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
226d0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
226e0 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
226f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
22700 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
22710 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22720 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
22730 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
22740 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
22750 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
22760 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
22770 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
22780 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
22790 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
227a0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
227b0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
227c0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
227d0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
227e0 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
227f0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
22800 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
22810 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
22820 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
22830 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
22840 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75  [conflict resolu
22850 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65  tion mode].** re
22860 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  turned from the 
22870 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
22880 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
22890 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
228a0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
228b0 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
228c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
228d0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
228e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
228f0 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
22900 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
22910 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
22920 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
22930 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22940 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
22950 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
22960 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
22970 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
22980 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
22990 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
229a0 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
229b0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
229c0 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
229d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
229e0 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
229f0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
22a00 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
22a10 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
22a20 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
22a30 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
22a40 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
22a50 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
22a60 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
22a70 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
22a80 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
22a90 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
22aa0 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
22ab0 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
22ac0 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
22ad0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
22ae0 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
22af0 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
22b00 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
22b10 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
22b20 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
22b30 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
22b40 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
22b50 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
22b60 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
22b70 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
22b80 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
22b90 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
22ba0 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
22bb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
22bc0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
22bd0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
22be0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
22bf0 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
22c00 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
22c10 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
22c20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
22c30 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
22c40 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
22c50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
22c60 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
22c70 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
22c80 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
22c90 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
22ca0 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
22cb0 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
22cc0 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
22cd0 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
22ce0 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
22cf0 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
22d00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22d10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22d20 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
22d30 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
22d40 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
22d50 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
22d60 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
22d70 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
22d80 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22d90 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22da0 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
22db0 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
22dc0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22dd0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22de0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22df0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
22e00 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
22e10 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
22e20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22e30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22e40 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
22e50 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
22e60 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22e70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22e80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22e90 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
22ea0 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
22eb0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
22ec0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22ed0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22ee0 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
22ef0 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
22f00 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
22f10 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22f20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22f30 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
22f40 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
22f50 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
22f60 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
22f70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22f80 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
22f90 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
22fa0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
22fb0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
22fc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
22fd0 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
22fe0 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
22ff0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
23000 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23010 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
23020 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
23030 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
23040 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
23050 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
23060 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
23070 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
23080 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
23090 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
230a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
230b0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
230c0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
230d0 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
230e0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
230f0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
23100 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
23110 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
23120 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
23130 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23140 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23150 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
23160 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
23170 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
23180 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
23190 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
231a0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
231b0 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
231c0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
231d0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
231e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
231f0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
23200 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
23210 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
23220 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
23230 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23240 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
23250 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
23260 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
23270 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23280 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23290 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
232a0 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
232b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
232c0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
232d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
232e0 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
232f0 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
23300 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
23310 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
23320 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23330 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
23340 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
23350 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
23360 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
23370 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23380 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
23390 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
233a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
233b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
233c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
233d0 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
233e0 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
233f0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
23400 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23410 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
23420 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
23430 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
23440 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
23450 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
23460 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
23470 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
23480 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
23490 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
234a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
234b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
234c0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
234d0 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
234e0 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
234f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23500 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
23510 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
23520 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
23530 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
23540 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
23550 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
23560 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
23570 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
23580 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
23590 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
235a0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
235b0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
235c0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
235d0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
235e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
235f0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
23600 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
23610 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
23620 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
23630 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
23640 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
23650 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
23660 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
23670 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
23680 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23690 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
236a0 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
236b0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
236c0 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
236d0 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
236e0 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
236f0 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
23700 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
23710 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
23720 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
23730 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
23740 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
23750 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
23760 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23770 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20  TE_RECURSIVE    
23780 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20          33   /* 
23790 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
237a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
237b0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
237c0 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
237d0 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
237e0 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
237f0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
23800 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
23810 64 65 70 72 65 63 61 74 65 64 2e 20 55 73 65 20  deprecated. Use 
23820 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
23830 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  ce_v2()] interfa
23840 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66  ce.** instead of
23850 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64 65   the routines de
23860 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a  scribed here..**
23870 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
23880 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
23890 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
238a0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
238b0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
238c0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
238d0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
238e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
238f0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
23900 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
23910 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
23920 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
23930 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
23940 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
23950 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
23960 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
23970 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
23980 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23990 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
239a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
239b0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
239c0 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
239d0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
239e0 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
239f0 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
23a00 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
23a10 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
23a20 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
23a30 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
23a40 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
23a50 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
23a60 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
23a70 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
23a80 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
23a90 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
23aa0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
23ab0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
23ac0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
23ad0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
23ae0 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
23af0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
23b00 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
23b10 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
23b20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
23b30 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
23b40 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
23b50 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
23b60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
23b70 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
23b80 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
23b90 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
23ba0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
23bb0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
23bc0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
23bd0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
23be0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
23bf0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
23c00 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
23c10 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
23c20 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
23c30 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
23c40 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
23c50 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
23c60 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
23c70 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
23c80 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
23c90 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
23ca0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
23cb0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
23cc0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
23cd0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
23ce0 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
23cf0 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
23d00 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
23d10 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
23d20 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
23d30 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
23d40 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
23d50 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
23d60 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
23d70 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
23d80 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
23d90 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
23da0 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
23db0 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
23dc0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
23dd0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
23de0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
23df0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
23e00 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
23e10 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
23e20 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
23e30 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
23e40 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
23e50 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
23e60 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
23e70 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
23e80 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
23e90 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
23ea0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
23eb0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
23ec0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
23ed0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72  CAPI3REF: SQL Tr
23ee0 61 63 65 20 45 76 65 6e 74 20 43 6f 64 65 73 0a  ace Event Codes.
23ef0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
23f00 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20  ITE_TRACE.**.** 
23f10 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
23f20 69 64 65 6e 74 69 66 79 20 63 6c 61 73 73 65 73  identify classes
23f30 20 6f 66 20 65 76 65 6e 74 73 20 74 68 61 74 20   of events that 
23f40 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64  can be monitored
23f50 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 73  .** using the [s
23f60 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23f70 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67 69 63  )] tracing logic
23f80 2e 20 20 54 68 65 20 4d 20 61 72 67 75 6d 65 6e  .  The M argumen
23f90 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  t.** to [sqlite3
23fa0 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c  _trace_v2(D,M,X,
23fb0 50 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20  P)] is an OR-ed 
23fc0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f  combination of o
23fd0 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a  ne or more of.**
23fe0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
23ff0 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20  onstants.  ^The 
24000 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
24010 6f 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c  o the trace call
24020 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f  back.** is one o
24030 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
24040 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
24050 20 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e   New tracing con
24060 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64  stants may be ad
24070 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
24080 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  leases..**.** ^A
24090 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
240a0 68 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e  has four argumen
240b0 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c  ts: xCallback(T,
240c0 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20  C,P,X)..** ^The 
240d0 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  T argument is on
240e0 65 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  e of the integer
240f0 20 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76   type codes abov
24100 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67  e..** ^The C arg
24110 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20  ument is a copy 
24120 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70  of the context p
24130 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
24140 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
24150 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
24160 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
24170 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64  )]..** The P and
24180 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65   X arguments are
24190 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20   pointers whose 
241a0 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20  meanings depend 
241b0 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  on T..**.** <dl>
241c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
241d0 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51  CE_STMT]] <dt>SQ
241e0 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c  LITE_TRACE_STMT<
241f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
24200 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
24210 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  T callback is in
24220 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65  voked when a pre
24230 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
24240 2a 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  ** first begins 
24250 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73  running and poss
24260 69 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69  ibly at other ti
24270 6d 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a  mes during the.*
24280 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  * execution of t
24290 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
242a0 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61  ement, such as a
242b0 74 20 74 68 65 20 73 74 61 72 74 20 6f 66 20 65  t the start of e
242c0 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73  ach.** trigger s
242d0 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20  ubprogram. ^The 
242e0 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
242f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
24300 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
24310 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61  ement]. ^The X a
24320 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
24330 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
24340 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65   which.** is the
24350 20 75 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20   unexpanded SQL 
24360 74 65 78 74 20 6f 66 20 74 68 65 20 70 72 65 70  text of the prep
24370 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
24380 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  r an SQL comment
24390 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
243a0 74 65 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69  tes the invocati
243b0 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e  on of a trigger.
243c0 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20    ^The callback 
243d0 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74  can compute.** t
243e0 68 65 20 73 61 6d 65 20 74 65 78 74 20 74 68 61  he same text tha
243f0 74 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65  t would have bee
24400 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
24410 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
24420 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e  3_trace()].** in
24430 74 65 72 66 61 63 65 20 62 79 20 75 73 69 6e 67  terface by using
24440 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20   the X argument 
24450 77 68 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69  when X begins wi
24460 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f  th "--" and invo
24470 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  king.** [sqlite3
24480 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29  _expanded_sql(P)
24490 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a  ] otherwise..**.
244a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
244b0 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e  E_PROFILE]] <dt>
244c0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f  SQLITE_TRACE_PRO
244d0 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FILE</dt>.** <dd
244e0 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43  >^An SQLITE_TRAC
244f0 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61  E_PROFILE callba
24500 63 6b 20 70 72 6f 76 69 64 65 73 20 61 70 70 72  ck provides appr
24510 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61  oximately the sa
24520 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  me.** informatio
24530 6e 20 61 73 20 69 73 20 70 72 6f 76 69 64 65 64  n as is provided
24540 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
24550 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c  _profile()] call
24560 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  back..** ^The P 
24570 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
24580 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72  inter to the [pr
24590 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
245a0 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61  ] and the.** X a
245b0 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
245c0 6f 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67  o a 64-bit integ
245d0 65 72 20 77 68 69 63 68 20 69 73 20 74 68 65 20  er which is the 
245e0 65 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20  estimated of.** 
245f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61  the number of na
24600 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68  nosecond that th
24610 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
24620 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
24630 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
24640 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63  _TRACE_PROFILE c
24650 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
24660 65 64 20 77 68 65 6e 20 74 68 65 20 73 74 61 74  ed when the stat
24670 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a  ement finishes..
24680 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
24690 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53  RACE_ROW]] <dt>S
246a0 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c  QLITE_TRACE_ROW<
246b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20  /dt>.** <dd>^An 
246c0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
246d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
246e0 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
246f0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
24700 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20  ement generates 
24710 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20  a single row of 
24720 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68  result.  .** ^Th
24730 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
24740 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
24750 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24760 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  ment] and the.**
24770 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75   X argument is u
24780 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  nused..**.** [[S
24790 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
247a0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  E]] <dt>SQLITE_T
247b0 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a  RACE_CLOSE</dt>.
247c0 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54  ** <dd>^An SQLIT
247d0 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61  E_TRACE_CLOSE ca
247e0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
247f0 64 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73  d when a databas
24800 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
24810 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20  closes..** ^The 
24820 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  P argument is a 
24830 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
24840 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24850 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  ion] object.** a
24860 6e 64 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e  nd the X argumen
24870 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20  t is unused..** 
24880 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
24890 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54   SQLITE_TRACE_ST
248a0 4d 54 20 20 20 20 20 20 20 30 78 30 31 0a 23 64  MT       0x01.#d
248b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
248c0 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78  CE_PROFILE    0x
248d0 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
248e0 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20  E_TRACE_ROW     
248f0 20 20 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20     0x04.#define 
24900 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
24910 53 45 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a  SE      0x08../*
24920 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
24930 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20  L Trace Hook.** 
24940 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
24950 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
24960 65 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c  e3_trace_v2(D,M,
24970 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 72  X,P) interface r
24980 65 67 69 73 74 65 72 73 20 61 20 74 72 61 63 65  egisters a trace
24990 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
249a0 63 74 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20  ction X against 
249b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
249c0 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70  tion] D, using p
249d0 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a  roperty mask M.*
249e0 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f  * and context po
249f0 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68  inter P.  ^If th
24a00 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a  e X callback is.
24a10 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68  ** NULL or if th
24a20 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f  e M mask is zero
24a30 2c 20 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69  , then tracing i
24a40 73 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65  s disabled.  The
24a50 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73  .** M argument s
24a60 68 6f 75 6c 64 20 62 65 20 74 68 65 20 62 69 74  hould be the bit
24a70 77 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69  wise OR-ed combi
24a80 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72  nation of.** zer
24a90 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54  o or more [SQLIT
24aa0 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e  E_TRACE] constan
24ab0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  ts..**.** ^Each 
24ac0 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73  call to either s
24ad0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f  qlite3_trace() o
24ae0 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  r sqlite3_trace_
24af0 76 32 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a  v2() overrides .
24b00 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79  ** (cancels) any
24b10 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20   prior calls to 
24b20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
24b30 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  or sqlite3_trace
24b40 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  _v2()..**.** ^Th
24b50 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e X callback is 
24b60 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
24b70 20 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e   any of the even
24b80 74 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  ts identified by
24b90 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75   .** mask M occu
24ba0 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72  r.  ^The integer
24bb0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
24bc0 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  om the callback 
24bd0 69 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  is currently.** 
24be0 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20  ignored, though 
24bf0 74 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20  this may change 
24c00 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
24c10 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a  es.  Callback.**
24c20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
24c30 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a   should return z
24c40 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75  ero to ensure fu
24c50 74 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69  ture compatibili
24c60 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61  ty..**.** ^A tra
24c70 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  ce callback is i
24c80 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72  nvoked with four
24c90 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c   arguments: call
24ca0 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
24cb0 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
24cc0 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
24cd0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a  [SQLITE_TRACE].*
24ce0 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69  * constants to i
24cf0 6e 64 69 63 61 74 65 20 77 68 79 20 74 68 65 20  ndicate why the 
24d00 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76  callback was inv
24d10 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20  oked..** ^The C 
24d20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f  argument is a co
24d30 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78  py of the contex
24d40 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68  t pointer..** Th
24d50 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
24d60 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
24d70 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
24d80 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
24d90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74  ** The sqlite3_t
24da0 72 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66  race_v2() interf
24db0 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20  ace is intended 
24dc0 74 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c  to replace the l
24dd0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
24de0 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  ces [sqlite3_tra
24df0 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ce()] and [sqlit
24e00 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62  e3_profile()], b
24e10 6f 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20  oth of which.** 
24e20 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a  are deprecated..
24e30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
24e40 72 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  race_v2(.  sqlit
24e50 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20  e3*,.  unsigned 
24e60 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43  uMask,.  int(*xC
24e70 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65  allback)(unsigne
24e80 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f  d,void*,void*,vo
24e90 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43  id*),.  void *pC
24ea0 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tx.);../*.** CAP
24eb0 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f  I3REF: Query Pro
24ec0 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a  gress Callbacks.
24ed0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
24ee0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
24ef0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
24f00 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
24f10 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
24f20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
24f30 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
24f40 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
24f50 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
24f60 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
24f70 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
24f80 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
24f90 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
24fa0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
24fb0 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
24fc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
24fd0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
24fe0 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
24ff0 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
25000 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
25010 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
25020 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
25030 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
25040 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
25050 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
25060 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
25070 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
25080 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
25090 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61  meter N is the a
250a0 70 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65  pproximate numbe
250b0 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
250c0 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
250d0 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
250e0 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
250f0 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
25100 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
25110 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20  the callback X. 
25120 20 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74   ^If N is less t
25130 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65  han one then the
25140 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e   progress.** han
25150 64 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  dler is disabled
25160 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
25170 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
25180 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
25190 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
251a0 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
251b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
251c0 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
251d0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
251e0 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
251f0 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
25200 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
25210 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
25220 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
25230 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
25240 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
25250 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
25260 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
25270 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
25280 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
25290 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
252a0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
252b0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
252c0 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
252d0 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
252e0 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
252f0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
25300 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
25310 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
25320 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
25330 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
25340 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
25350 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
25360 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
25370 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
25380 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
25390 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
253a0 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
253b0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
253c0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
253d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
253e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
253f0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
25400 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
25410 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
25420 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
25430 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
25440 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
25450 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
25460 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
25470 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c  r(sqlite3*, int,
25480 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
25490 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
254a0 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67  API3REF: Opening
254b0 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20   A New Database 
254c0 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f  Connection.** CO
254d0 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
254e0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
254f0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
25500 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
25510 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
25520 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
25530 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
25540 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
25550 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
25560 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
25570 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
25580 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
25590 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
255a0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
255b0 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
255c0 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
255d0 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
255e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
255f0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
25600 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
25610 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
25620 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
25630 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
25640 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
25650 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
25660 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
25670 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
25680 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
25690 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
256a0 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
256b0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
256c0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
256d0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
256e0 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
256f0 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
25700 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
25710 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
25720 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
25730 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
25740 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
25750 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
25760 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
25770 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
25780 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
25790 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
257a0 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
257b0 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
257c0 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
257d0 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
257e0 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
257f0 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
25800 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
25810 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
25820 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
25830 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
25840 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
25850 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46  ding will be UTF
25860 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  -8 for databases
25870 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a   created using.*
25880 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
25890 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
258a0 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66  _v2().  ^The def
258b0 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
258c0 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63  r databases.** c
258d0 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c  reated using sql
258e0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69  ite3_open16() wi
258f0 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20  ll be UTF-16 in 
25900 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
25910 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  order..**.** Whe
25920 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65  ther or not an e
25930 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e  rror occurs when
25940 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72   it is opened, r
25950 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f  esources.** asso
25960 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
25970 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25980 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f  tion] handle sho
25990 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20  uld be released 
259a0 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74  by.** passing it
259b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
259c0 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73  se()] when it is
259d0 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69   no longer requi
259e0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  red..**.** The s
259f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25a00 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73   interface works
25a10 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70   like sqlite3_op
25a20 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74  en().** except t
25a30 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74  hat it accepts t
25a40 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61  wo additional pa
25a50 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64  rameters for add
25a60 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a  itional control.
25a70 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20  ** over the new 
25a80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
25a90 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67  ion.  ^(The flag
25aa0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
25ab0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  * sqlite3_open_v
25ac0 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65  2() can take one
25ad0 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f   of.** the follo
25ae0 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65  wing three value
25af0 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f  s, optionally co
25b00 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20  mbined with the 
25b10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
25b20 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  _NOMUTEX], [SQLI
25b30 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
25b40 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
25b50 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a  _SHAREDCACHE],.*
25b60 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
25b70 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e  RIVATECACHE], an
25b80 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  d/or [SQLITE_OPE
25b90 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a  N_URI] flags:)^.
25ba0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28  **.** <dl>.** ^(
25bb0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
25bc0 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a  _READONLY]</dt>.
25bd0 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
25be0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e  ase is opened in
25bf0 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e   read-only mode.
25c00 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73    If the databas
25c10 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c  e does not.** al
25c20 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20  ready exist, an 
25c30 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
25c40 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
25c50 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
25c60 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64  EN_READWRITE]</d
25c70 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
25c80 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
25c90 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
25ca0 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73   writing if poss
25cb0 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67  ible, or reading
25cc0 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  .** only if the 
25cd0 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72  file is write pr
25ce0 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f  otected by the o
25cf0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
25d00 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63    In either.** c
25d10 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ase the database
25d20 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78   must already ex
25d30 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61  ist, otherwise a
25d40 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
25d50 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
25d60 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
25d70 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
25d80 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
25d90 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
25da0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
25db0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
25dc0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
25dd0 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
25de0 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  d if.** it does 
25df0 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  not already exis
25e00 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62  t. This is the b
25e10 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20  ehavior that is 
25e20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a  always used for.
25e30 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
25e40 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
25e50 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a  en16().</dd>)^.*
25e60 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66  * </dl>.**.** If
25e70 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
25e80 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
25e90 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f  en_v2() is not o
25ea0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d  ne of the.** com
25eb0 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
25ec0 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79  above optionally
25ed0 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f   combined with o
25ee0 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ther.** [SQLITE_
25ef0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  OPEN_READONLY | 
25f00 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69  SQLITE_OPEN_* bi
25f10 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ts].** then the 
25f20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
25f30 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  fined..**.** ^If
25f40 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
25f50 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20  N_NOMUTEX] flag 
25f60 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65  is set, then the
25f70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25f80 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e  tion.** opens in
25f90 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61   the multi-threa
25fa0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
25fb0 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  e] as long as th
25fc0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a  e single-thread.
25fd0 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20  ** mode has not 
25fe0 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70  been set at comp
25ff0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
26000 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65  t-time.  ^If the
26010 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
26020 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67  _FULLMUTEX] flag
26030 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65   is set then the
26040 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26050 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e  tion opens.** in
26060 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20   the serialized 
26070 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
26080 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74   unless single-t
26090 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65  hread was.** pre
260a0 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64  viously selected
260b0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
260c0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a   or start-time..
260d0 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
260e0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
260f0 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
26100 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
26110 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65  ction to be.** e
26120 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b  ligible to use [
26130 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
26140 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f  e], regardless o
26150 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
26160 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
26170 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e   is enabled usin
26180 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  g [sqlite3_enabl
26190 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29  e_shared_cache()
261a0 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c  ].  ^The.** [SQL
261b0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
261c0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
261d0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
261e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
261f0 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
26200 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
26210 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
26220 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
26230 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
26240 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
26250 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
26260 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
26270 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
26280 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  fs] object that 
26290 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72  defines the oper
262a0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
262b0 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74  erface that.** t
262c0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
262d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c  connection shoul
262e0 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20  d use.  ^If the 
262f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
26300 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f   is.** a NULL po
26310 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64  inter then the d
26320 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
26330 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75  vfs] object is u
26340 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  sed..**.** ^If t
26350 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22  he filename is "
26360 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20  :memory:", then 
26370 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
26380 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  rary in-memory d
26390 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72  atabase.** is cr
263a0 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f  eated for the co
263b0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73  nnection.  ^This
263c0 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
263d0 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20  ase will vanish 
263e0 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  when.** the data
263f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
26400 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75  is closed.  Futu
26410 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
26420 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d  QLite might.** m
26430 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74  ake use of addit
26440 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69  ional special fi
26450 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67  lenames that beg
26460 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20  in with the ":" 
26470 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74  character..** It
26480 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
26490 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61  that when a data
264a0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63  base filename ac
264b0 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69  tually does begi
264c0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20  n with.** a ":" 
264d0 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68  character you sh
264e0 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20  ould prefix the 
264f0 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20  filename with a 
26500 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73  pathname such as
26510 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69  .** "./" to avoi
26520 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a  d ambiguity..**.
26530 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
26540 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20  ame is an empty 
26550 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70  string, then a p
26560 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72  rivate, temporar
26570 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74  y.** on-disk dat
26580 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72  abase will be cr
26590 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72  eated.  ^This pr
265a0 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
265b0 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
265c0 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
265d0 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
265e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
265f0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
26600 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
26610 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f  mes in sqlite3_o
26620 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20  pen()]] <h3>URI 
26630 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a  Filenames</h3>.*
26640 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69  *.** ^If [URI fi
26650 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65  lename] interpre
26660 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
26670 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e  d, and the filen
26680 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
26690 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c  begins with "fil
266a0 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69  e:", then the fi
266b0 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70  lename is interp
266c0 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20  reted as a URI. 
266d0 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ^URI.** filename
266e0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
266f0 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
26700 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
26710 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73  RI] flag is.** s
26720 65 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  et in the third 
26730 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
26740 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
26750 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
26760 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
26770 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
26780 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
26790 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
267a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
267b0 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
267c0 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
267d0 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
267e0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
267f0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
26800 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
26810 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
26820 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
26830 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
26840 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
26850 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
26860 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
26870 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
26880 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
26890 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
268a0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
268b0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
268c0 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
268d0 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
268e0 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
268f0 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
26900 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
26910 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
26920 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
26930 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
26940 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
26950 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
26960 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
26970 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
26980 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
26990 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
269a0 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
269b0 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
269c0 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
269d0 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
269e0 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
269f0 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
26a00 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
26a10 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
26a20 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
26a30 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
26a40 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
26a50 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
26a60 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
26a70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
26a80 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
26a90 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
26aa0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
26ab0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
26ac0 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
26ad0 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
26ae0 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
26af0 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
26b00 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
26b10 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
26b20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
26b30 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
26b40 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
26b50 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
26b60 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74   ^(On windows, t
26b70 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65  he first compone
26b80 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74  nt of an absolut
26b90 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20  e path .** is a 
26ba0 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74  drive specificat
26bb0 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e  ion (e.g. "C:").
26bc0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )^.**.** [[core 
26bd0 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
26be0 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
26bf0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
26c00 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
26c10 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
26c20 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
26c30 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
26c40 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
26c50 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
26c60 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
26c70 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
26c80 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c  ite and its buil
26c90 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74  t-in [VFSes] int
26ca0 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f  erpret the.** fo
26cb0 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61  llowing query pa
26cc0 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
26cd0 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
26ce0 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
26cf0 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
26d00 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
26d10 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
26d20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
26d30 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
26d40 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
26d50 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
26d60 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
26d70 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
26d80 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
26d90 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
26da0 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
26db0 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
26dc0 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
26dd0 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
26de0 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
26df0 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
26e00 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
26e10 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
26e20 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
26e30 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
26e40 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
26e50 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
26e60 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
26e70 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
26e80 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
26e90 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
26ea0 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
26eb0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
26ec0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
26ed0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
26ee0 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
26ef0 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
26f00 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
26f10 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
26f20 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
26f30 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
26f40 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
26f50 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
26f60 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
26f70 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
26f80 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
26f90 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
26fa0 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
26fb0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
26fc0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
26fd0 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
26fe0 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
26ff0 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
27000 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
27010 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
27020 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
27030 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
27040 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
27050 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
27060 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
27070 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
27080 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
27090 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
270a0 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
270b0 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
270c0 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
270d0 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
270e0 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
270f0 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
27100 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
27110 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
27120 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
27130 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
27140 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
27150 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
27160 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
27170 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20  E_OPEN_CREATE.  
27180 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
27190 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65  ion is.**     se
271a0 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68  t to "memory" th
271b0 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65  en a pure [in-me
271c0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74  mory database] t
271d0 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a  hat never reads.
271e0 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73  **     or writes
271f0 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73   from disk is us
27200 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72  ed. ^It is an er
27210 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
27220 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20   value for.**   
27230 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d    the mode param
27240 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73  eter that is les
27250 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
27260 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
27270 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20  d by.**     the 
27280 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20  flags passed in 
27290 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
272a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
272b0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
272c0 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
272d0 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
272e0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
272f0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
27300 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
27310 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
27320 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
27330 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
27340 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
27350 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
27360 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
27370 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
27380 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
27390 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
273a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
273b0 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
273c0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
273d0 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
273e0 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
273f0 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
27400 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
27410 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
27420 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
27430 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
27440 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
27450 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
27460 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
27470 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
27480 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
27490 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72  des any behavior
274a0 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
274b0 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
274c0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
274d0 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
274e0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
274f0 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c   flag..**.**  <l
27500 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20  i> <b>psow</b>: 
27510 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65  ^The psow parame
27520 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68  ter indicates wh
27530 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
27540 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61  .**     [powersa
27550 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72  fe overwrite] pr
27560 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64  operty does or d
27570 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f  oes not apply to
27580 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72   the.**     stor
27590 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69  age media on whi
275a0 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
275b0 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a  file resides..**
275c0 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c  .**  <li> <b>nol
275d0 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f  ock</b>: ^The no
275e0 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  lock parameter i
275f0 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
27600 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  y parameter.**  
27610 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20     which if set 
27620 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f  disables file lo
27630 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63  cking in rollbac
27640 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e  k journal modes.
27650 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73    This.**     is
27660 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65   useful for acce
27670 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65  ssing a database
27680 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d   on a filesystem
27690 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a   that does not.*
276a0 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f  *     support lo
276b0 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a  cking.  Caution:
276c0 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75    Database corru
276d0 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75  ption might resu
276e0 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20  lt if two.**    
276f0 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73   or more process
27700 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20  es write to the 
27710 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e  same database an
27720 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f  d any one of tho
27730 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73  se.**     proces
27740 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d  ses uses nolock=
27750 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  1..**.**  <li> <
27760 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a  b>immutable</b>:
27770 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20   ^The immutable 
27780 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
27790 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20  oolean query.** 
277a0 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68      parameter th
277b0 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  at indicates tha
277c0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  t the database f
277d0 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e  ile is stored on
277e0 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c  .**     read-onl
277f0 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20  y media.  ^When 
27800 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74  immutable is set
27810 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  , SQLite assumes
27820 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
27830 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63   database file c
27840 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
27850 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63  , even by a proc
27860 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a  ess with higher.
27870 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65  **     privilege
27880 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74  , and so the dat
27890 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
278a0 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c  read-only and al
278b0 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20  l locking.**    
278c0 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65   and change dete
278d0 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65  ction is disable
278e0 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74  d.  Caution: Set
278f0 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62  ting the immutab
27900 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72  le.**     proper
27910 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ty on a database
27920 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20   file that does 
27930 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63  in fact change c
27940 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20  an result.**    
27950 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75   in incorrect qu
27960 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f  ery results and/
27970 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  or [SQLITE_CORRU
27980 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20  PT] errors..**  
27990 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51     See also: [SQ
279a0 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
279b0 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20  ABLE]..**       
279c0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
279d0 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
279e0 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72  nknown parameter
279f0 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f   in the query co
27a00 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
27a10 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72   is not an.** er
27a20 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72  ror.  Future ver
27a30 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
27a40 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64  might understand
27a50 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72   additional quer
27a60 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  y.** parameters.
27a70 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61    See "[query pa
27a80 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70  rameters with sp
27a90 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
27aa0 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a   SQLite]" for.**
27ab0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
27ac0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  rmation..**.** [
27ad0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  [URI filename ex
27ae0 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49  amples]] <h3>URI
27af0 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
27b00 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74  es</h3>.**.** <t
27b10 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
27b20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c  align=center cel
27b30 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c  lpadding=5>.** <
27b40 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65  tr><th> URI file
27b50 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c  names <th> Resul
27b60 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  ts.** <tr><td> f
27b70 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e  ile:data.db <td>
27b80 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
27b90 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
27ba0 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
27bb0 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a  rent directory..
27bc0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
27bd0 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
27be0 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20  .db<br>.**      
27bf0 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65      file:///home
27c00 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
27c10 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r> .**          
27c20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74  file://localhost
27c30 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
27c40 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a  db <br> <td> .**
27c50 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
27c60 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27c70 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
27c80 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  a.db"..** <tr><t
27c90 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74  d> file://darkst
27ca0 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ar/home/fred/dat
27cb0 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
27cc0 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
27cd0 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e   "darkstar" is n
27ce0 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20  ot a recognized 
27cf0 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74  authority..** <t
27d00 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69  r><td style="whi
27d10 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22  te-space:nowrap"
27d20 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
27d30 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65  ile:///C:/Docume
27d40 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74  nts%20and%20Sett
27d50 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f  ings/fred/Deskto
27d60 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20  p/data.db.**    
27d70 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e   <td> Windows on
27d80 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c  ly: Open the fil
27d90 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66  e "data.db" on f
27da0 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e  red's desktop on
27db0 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20   drive.**       
27dc0 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74     C:. Note that
27dd0 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e   the %20 escapin
27de0 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c  g in this exampl
27df0 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c  e is not strictl
27e00 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  y .**          n
27e10 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65  ecessary - space
27e20 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20   characters can 
27e30 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c  be used literall
27e40 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  y.**          in
27e50 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a   URI filenames..
27e60 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
27e70 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f  :data.db?mode=ro
27e80 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c  &cache=private <
27e90 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
27ea0 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61   Open file "data
27eb0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
27ec0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f  ent directory fo
27ed0 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65  r read-only acce
27ee0 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss..**          
27ef0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
27f00 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
27f10 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69  red-cache mode i
27f20 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20  s enabled by.** 
27f30 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74           default
27f40 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20  , use a private 
27f50 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cache..** <tr><t
27f60 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
27f70 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75  ed/data.db?vfs=u
27f80 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e  nix-dotfile <td>
27f90 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
27fa0 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  n file "/home/fr
27fb0 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65  ed/data.db". Use
27fc0 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
27fd0 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a   "unix-dotfile".
27fe0 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
27ff0 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20   uses dot-files 
28000 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69  in place of posi
28010 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69  x advisory locki
28020 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ng..** <tr><td> 
28030 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
28040 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
28050 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
28060 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
28070 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
28080 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
28090 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
280a0 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
280b0 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
280c0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
280d0 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
280e0 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
280f0 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
28100 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
28110 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
28120 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
28130 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
28140 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
28150 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
28160 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
28170 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
28180 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
28190 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
281a0 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
281b0 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
281c0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
281d0 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
281e0 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
281f0 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
28200 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
28210 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
28220 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
28230 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
28240 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
28250 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
28260 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
28270 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
28280 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
28290 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
282a0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
282b0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
282c0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
282d0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
282e0 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
282f0 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
28300 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
28310 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
28320 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
28330 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
28340 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
28350 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
28360 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
28370 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
28380 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
28390 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
283a0 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
283b0 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
283c0 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
283d0 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
283e0 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
283f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
28400 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
28410 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c  en_v2()..**.** <
28420 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
28430 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a  s Runtime users:
28440 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72  </b>  The tempor
28450 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75  ary directory mu
28460 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69  st be set.** pri
28470 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71  or to calling sq
28480 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
28490 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
284a0 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76  ).  Otherwise, v
284b0 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72  arious.** featur
284c0 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20  es that require 
284d0 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f  the use of tempo
284e0 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66  rary files may f
284f0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ail..**.** See a
28500 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65  lso: [sqlite3_te
28510 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f  mp_directory].*/
28520 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
28530 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
28540 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
28550 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
28560 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
28570 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
28580 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
28590 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
285a0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
285b0 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
285c0 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
285d0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
285e0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
285f0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
28600 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
28610 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
28620 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
28630 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
28640 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
28650 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
28660 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
28670 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
28680 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
28690 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
286a0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
286b0 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
286c0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
286d0 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
286e0 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
286f0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
28700 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
28710 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
28720 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
28730 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
28740 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
28750 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20  ese are utility 
28760 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c  routines, useful
28770 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e   to VFS implemen
28780 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68  tations, that ch
28790 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  eck.** to see if
287a0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
287b0 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
287c0 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
287d0 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
287e0 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
287f0 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
28800 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75  value of that qu
28810 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ery parameter..*
28820 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65  *.** If F is the
28830 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
28840 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  me pointer passe
28850 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
28860 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a  () method of .**
28870 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74   a VFS implement
28880 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66  ation when the f
28890 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
288a0 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e  o xOpen() has on
288b0 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66  e or .** more of
288c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
288d0 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54  N_URI] or [SQLIT
288e0 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20  E_OPEN_MAIN_DB] 
288f0 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20  bits set and.** 
28900 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  P is the name of
28910 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d   the query param
28920 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  eter, then.** sq
28930 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
28940 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
28950 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
28960 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  e P.** parameter
28970 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72   if it exists or
28980 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
28990 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70  if P does not ap
289a0 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75  pear as a .** qu
289b0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  ery parameter on
289c0 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71   F.  If P is a q
289d0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
289e0 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78  f F.** has no ex
289f0 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68  plicit value, th
28a00 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
28a10 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
28a20 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  turns.** a point
28a30 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  er to an empty s
28a40 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
28a50 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
28a60 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
28a70 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ine assumes that
28a80 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a   P is a boolean.
28a90 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  ** parameter and
28aa0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
28ab0 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61  ) or false (0) a
28ac0 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20  ccording to the 
28ad0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20  value.** of P.  
28ae0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
28af0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
28b00 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
28b10 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a  rue (1) if the.*
28b20 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79  * value of query
28b30 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
28b40 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74  one of "yes", "t
28b50 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e  rue", or "on" in
28b60 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20   any.** case or 
28b70 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
28b80 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ins with a non-z
28b90 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ero number.  The
28ba0 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69   .** sqlite3_uri
28bb0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
28bc0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73  routines returns
28bd0 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68   false (0) if th
28be0 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75  e value of.** qu
28bf0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
28c00 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20  is one of "no", 
28c10 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66  "false", or "off
28c20 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72  " in any case or
28c30 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65  .** if the value
28c40 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
28c50 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66  umeric zero.  If
28c60 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72   P is not a quer
28c70 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
28c80 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61  n F or if the va
28c90 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73  lue of P is does
28ca0 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f   not match any o
28cb0 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20  f the.** above, 
28cc0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
28cd0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
28ce0 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a  returns (B!=0)..
28cf0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
28d00 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c  3_uri_int64(F,P,
28d10 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65  D) routine conve
28d20 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rts the value of
28d30 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d   P into a.** 64-
28d40 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
28d50 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
28d60 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20  hat integer, or 
28d70 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a  D if P does not.
28d80 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68  ** exist.  If th
28d90 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
28da0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
28db0 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c  than an integer,
28dc0 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73   then.** zero is
28dd0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a   returned..** .*
28de0 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c  * If F is a NULL
28df0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73   pointer, then s
28e00 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
28e10 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
28e20 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71  s NULL and.** sq
28e30 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
28e40 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
28e50 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74   B.  If F is not
28e60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
28e70 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20  and.** is not a 
28e80 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61  database file pa
28e90 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74  thname pointer t
28ea0 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65  hat SQLite passe
28eb0 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
28ec0 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20  .** VFS method, 
28ed0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
28ee0 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  r of this routin
28ef0 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  e is undefined a
28f00 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75  nd probably.** u
28f10 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63  ndesirable..*/.c
28f20 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
28f30 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
28f40 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
28f50 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
28f60 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74  ar *zParam);.int
28f70 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
28f80 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
28f90 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
28fa0 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
28fb0 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74  bDefault);.sqlit
28fc0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
28fd0 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
28fe0 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
28ff0 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
29000 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
29010 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
29020 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
29030 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
29040 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e3.**.** ^If the
29050 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c   most recent sql
29060 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
29070 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
29080 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
29090 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c  nnection] D fail
290a0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ed, then the sql
290b0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20  ite3_errcode(D) 
290c0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
290d0 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
290e0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
290f0 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
29100 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61  lt code] for tha
29110 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a  t.** API call..*
29120 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  * If the most re
29130 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61  cent API call wa
29140 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a  s successful,.**
29150 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
29160 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
29170 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
29180 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
29190 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
291a0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
291b0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
291c0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
291d0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
291e0 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
291f0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
29200 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
29210 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
29220 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
29230 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
29240 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
29250 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
29260 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
29270 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
29280 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
29290 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
292a0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
292b0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
292c0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
292d0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
292e0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
292f0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
29300 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
29310 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
29320 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
29330 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
29340 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
29350 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
29360 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
29370 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
29380 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
29390 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
293a0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
293b0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
293c0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
293d0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
293e0 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
293f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
29400 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
29410 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
29420 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
29430 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
29440 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
29450 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
29460 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
29470 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
29480 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
29490 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
294a0 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
294b0 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
294c0 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
294d0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
294e0 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
294f0 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
29500 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
29510 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
29520 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
29530 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
29540 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
29550 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
29560 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
29570 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
29580 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
29590 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
295a0 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
295b0 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
295c0 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
295d0 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
295e0 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
295f0 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
29600 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
29610 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
29620 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
29630 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
29640 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29650 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
29660 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
29670 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
29680 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
29690 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
296a0 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
296b0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
296c0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
296d0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
296e0 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
296f0 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
29700 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
29710 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
29720 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
29730 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
29740 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
29750 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
29760 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
29770 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
29780 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
29790 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
297a0 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
297b0 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
297c0 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
297d0 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
297e0 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
297f0 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
29800 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
29810 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
29820 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
29830 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
29840 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
29850 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
29860 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
29870 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
29880 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
29890 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
298a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
298b0 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74  F: Prepared Stat
298c0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
298d0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
298e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
298f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29900 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
29910 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
29920 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
29930 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
29940 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20  atement that.** 
29950 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65  has been compile
29960 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f  d into binary fo
29970 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20  rm and is ready 
29980 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e  to be evaluated.
29990 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20  .**.** Think of 
299a0 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
299b0 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65  nt as a separate
299c0 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61   computer progra
299d0 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69  m.  The.** origi
299e0 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20  nal SQL text is 
299f0 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20  source code.  A 
29a00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29a10 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73  nt object .** is
29a20 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62   the compiled ob
29a30 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20  ject code.  All 
29a40 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  SQL must be conv
29a50 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20  erted into a.** 
29a60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29a70 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e  nt before it can
29a80 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54   be run..**.** T
29a90 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66  he life-cycle of
29aa0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
29ab0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75  ement object usu
29ac0 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74  ally goes like t
29ad0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
29ae0 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
29af0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
29b00 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69  ement object usi
29b10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
29b20 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c  are_v2()]..** <l
29b30 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
29b40 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75  o [parameters] u
29b50 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
29b60 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
29b70 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
29b80 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
29b90 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
29ba0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
29bb0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
29bc0 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
29bd0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
29be0 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
29bf0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
29c00 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
29c10 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
29c20 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
29c30 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
29c40 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
29c50 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
29c60 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
29c70 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79  ..** </ol>.*/.ty
29c80 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
29c90 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
29ca0 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
29cb0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
29cc0 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48  e Limits.** METH
29cd0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
29ce0 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
29cf0 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
29d00 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
29d10 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
29d20 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
29d30 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
29d40 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
29d50 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
29d60 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
29d70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29d80 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
29d90 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
29da0 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
29db0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
29dc0 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
29dd0 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
29de0 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
29df0 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
29e00 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
29e10 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
29e20 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
29e30 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
29e40 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
29e50 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
29e60 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
29e70 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
29e80 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
29e90 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
29ea0 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
29eb0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
29ec0 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
29ed0 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
29ee0 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
29ef0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
29f00 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
29f10 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
29f20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
29f30 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
29f40 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
29f50 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
29f60 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
29f70 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
29f80 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
29f90 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
29fa0 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
29fb0 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
29fc0 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
29fd0 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
29fe0 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
29ff0 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
2a000 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
2a010 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2a020 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
2a030 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
2a040 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
2a050 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
2a060 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2a070 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
2a080 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
2a090 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
2a0a0 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
2a0b0 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
2a0c0 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
2a0d0 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
2a0e0 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
2a0f0 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
2a100 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
2a110 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
2a120 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
2a130 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
2a140 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
2a150 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
2a160 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
2a170 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
2a180 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
2a190 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
2a1a0 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
2a1b0 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
2a1c0 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
2a1d0 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
2a1e0 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
2a1f0 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
2a200 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
2a210 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
2a220 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
2a230 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
2a240 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
2a250 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
2a260 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
2a270 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
2a280 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
2a290 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
2a2a0 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
2a2b0 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
2a2c0 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
2a2d0 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
2a2e0 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
2a2f0 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
2a300 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
2a310 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
2a320 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
2a330 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
2a340 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
2a350 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
2a360 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
2a370 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
2a380 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
2a390 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
2a3a0 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
2a3b0 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
2a3c0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
2a3d0 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
2a3e0 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
2a3f0 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
2a400 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
2a410 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
2a420 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
2a430 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
2a440 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
2a450 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
2a460 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
2a470 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ases..*/.int sql
2a480 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
2a490 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
2a4a0 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
2a4b0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
2a4c0 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
2a4d0 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
2a4e0 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
2a4f0 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
2a500 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
2a510 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
2a520 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
2a530 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
2a540 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
2a550 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
2a560 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
2a570 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
2a580 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
2a590 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
2a5a0 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
2a5b0 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
2a5c0 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
2a5d0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
2a5e0 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
2a5f0 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
2a600 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
2a610 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  l>.** [[SQLITE_L
2a620 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  IMIT_LENGTH]] ^(
2a630 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2a640 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
2a650 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2a660 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
2a670 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
2a680 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65  ble row, in byte
2a690 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  s.<dd>)^.**.** [
2a6a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  [SQLITE_LIMIT_SQ
2a6b0 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  L_LENGTH]] ^(<dt
2a6c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
2a6d0 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
2a6e0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a6f0 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
2a700 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20  L statement, in 
2a710 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  bytes.</dd>)^.**
2a720 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2a730 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64  IT_COLUMN]] ^(<d
2a740 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
2a750 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
2a760 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2a770 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2a780 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
2a790 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
2a7a0 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
2a7b0 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
2a7c0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2a7d0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2a7e0 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
2a7f0 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
2a800 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
2a810 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2a820 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  [SQLITE_LIMIT_EX
2a830 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  PR_DEPTH]] ^(<dt
2a840 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
2a850 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
2a860 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2a870 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
2a880 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
2a890 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
2a8a0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2a8b0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
2a8c0 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e  _SELECT]] ^(<dt>
2a8d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
2a8e0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
2a8f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2a900 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
2a910 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
2a920 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
2a930 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
2a940 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
2a950 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74  _VDBE_OP]] ^(<dt
2a960 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
2a970 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
2a980 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2a990 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
2a9a0 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
2a9b0 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
2a9c0 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
2a9d0 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
2a9e0 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71  atement.  If [sq
2a9f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2aa00 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71  ()] or.** the eq
2aa10 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20 74  uivalent tries t
2aa20 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63 65  o allocate space
2aa30 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20 74   for more than t
2aa40 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73  his many opcodes
2aa50 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65 20  .** in a single 
2aa60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2aa70 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f  nt, an SQLITE_NO
2aa80 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65 74  MEM error is ret
2aa90 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
2aaa0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2aab0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
2aac0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2aad0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2aae0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
2aaf0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2ab00 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
2ab10 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
2ab20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2ab30 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
2ab40 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  D]] ^(<dt>SQLITE
2ab50 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
2ab60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2ab70 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2ab80 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
2ab90 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
2aba0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
2abb0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
2abc0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
2abd0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
2abe0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
2abf0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
2ac00 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2ac10 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
2ac20 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
2ac30 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
2ac40 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
2ac50 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
2ac60 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2ac70 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2ac80 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  UMBER]].** ^(<dt
2ac90 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
2aca0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
2acb0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2acc0 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
2acd0 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
2ace0 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
2acf0 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
2ad00 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2ad10 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d  T_TRIGGER_DEPTH]
2ad20 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2ad30 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
2ad40 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2ad50 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
2ad60 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
2ad70 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
2ad80 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2ad90 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
2ada0 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53  HREADS]] ^(<dt>S
2adb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
2adc0 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a  ER_THREADS</dt>.
2add0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2ade0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78  um number of aux
2adf0 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68  iliary worker th
2ae00 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e  reads that a sin
2ae10 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  gle.** [prepared
2ae20 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20   statement] may 
2ae30 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  start.</dd>)^.**
2ae40 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
2ae50 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
2ae60 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
2ae70 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
2ae80 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2ae90 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
2aea0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2aeb0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2aec0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
2aed0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
2aee0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2aef0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
2af00 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
2af10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2af20 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
2af30 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
2af40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2af50 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
2af60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
2af70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2af80 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2af90 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
2afa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2afb0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
2afc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2afd0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
2afe0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
2aff0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
2b000 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
2b010 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2b020 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
2b030 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
2b040 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
2b050 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
2b060 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
2b070 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
2b080 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20  _THREADS        
2b090 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     11../*.** CAP
2b0a0 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 20 46  I3REF: Prepare F
2b0b0 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lags.**.** These
2b0c0 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
2b0d0 65 20 76 61 72 69 6f 75 73 20 66 6c 61 67 73 20  e various flags 
2b0e0 74 68 61 74 20 63 61 6e 20 62 65 20 70 61 73 73  that can be pass
2b0f0 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 70 72 65 70  ed into.** "prep
2b100 46 6c 61 67 73 22 20 70 61 72 61 6d 65 74 65 72  Flags" parameter
2b110 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2b120 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 61  _prepare_v3()] a
2b130 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
2b140 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20 69  repare16_v3()] i
2b150 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a  nterfaces..**.**
2b160 20 4e 65 77 20 66 6c 61 67 73 20 6d 61 79 20 62   New flags may b
2b170 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
2b180 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
2b190 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  Lite..**.** <dl>
2b1a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 50 52 45  .** [[SQLITE_PRE
2b1b0 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 5d  PARE_PERSISTENT]
2b1c0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 50  ] ^(<dt>SQLITE_P
2b1d0 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2b1e0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
2b1f0 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  e SQLITE_PREPARE
2b200 5f 50 45 52 53 49 53 54 45 4e 54 20 66 6c 61 67  _PERSISTENT flag
2b210 20 69 73 20 61 20 68 69 6e 74 20 74 6f 20 74 68   is a hint to th
2b220 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 0a  e query planner.
2b230 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 65 70  ** that the prep
2b240 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77  ared statement w
2b250 69 6c 6c 20 62 65 20 72 65 74 61 69 6e 65 64 20  ill be retained 
2b260 66 6f 72 20 61 20 6c 6f 6e 67 20 74 69 6d 65 20  for a long time 
2b270 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 62 6c 79 20  and.** probably 
2b280 72 65 75 73 65 64 20 6d 61 6e 79 20 74 69 6d 65  reused many time
2b290 73 2e 29 5e 20 5e 57 69 74 68 6f 75 74 20 74 68  s.)^ ^Without th
2b2a0 69 73 20 66 6c 61 67 2c 20 5b 73 71 6c 69 74 65  is flag, [sqlite
2b2b0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 0a  3_prepare_v3()].
2b2c0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2b2d0 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20  prepare16_v3()] 
2b2e0 61 73 73 75 6d 65 20 74 68 61 74 20 74 68 65 20  assume that the 
2b2f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b300 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 62 65 20 75  nt will .** be u
2b310 73 65 64 20 6a 75 73 74 20 6f 6e 63 65 20 6f 72  sed just once or
2b320 20 61 74 20 6d 6f 73 74 20 61 20 66 65 77 20 74   at most a few t
2b330 69 6d 65 73 20 61 6e 64 20 74 68 65 6e 20 64 65  imes and then de
2b340 73 74 72 6f 79 65 64 20 75 73 69 6e 67 0a 2a 2a  stroyed using.**
2b350 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2b360 7a 65 28 29 5d 20 72 65 6c 61 74 69 76 65 6c 79  ze()] relatively
2b370 20 73 6f 6f 6e 2e 20 54 68 65 20 63 75 72 72 65   soon. The curre
2b380 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
2b390 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e 20 74 68 69  n acts.** on thi
2b3a0 73 20 68 69 6e 74 20 62 79 20 61 76 6f 69 64 69  s hint by avoidi
2b3b0 6e 67 20 74 68 65 20 75 73 65 20 6f 66 20 5b 6c  ng the use of [l
2b3c0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 5d  ookaside memory]
2b3d0 20 73 6f 20 61 73 20 6e 6f 74 20 74 6f 0a 2a 2a   so as not to.**
2b3e0 20 64 65 70 6c 65 74 65 20 74 68 65 20 6c 69 6d   deplete the lim
2b3f0 69 74 65 64 20 73 74 6f 72 65 20 6f 66 20 6c 6f  ited store of lo
2b400 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 20  okaside memory. 
2b410 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
2b420 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 79  of.** SQLite may
2b430 20 61 63 74 20 6f 6e 20 74 68 69 73 20 68 69 6e   act on this hin
2b440 74 20 64 69 66 66 65 72 65 6e 74 6c 79 2e 0a 2a  t differently..*
2b450 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
2b460 6e 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52  ne SQLITE_PREPAR
2b470 45 5f 50 45 52 53 49 53 54 45 4e 54 20 20 20 20  E_PERSISTENT    
2b480 20 20 20 20 20 20 20 20 20 20 30 78 30 31 0a 0a            0x01..
2b490 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b4a0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
2b4b0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
2b4c0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
2b4d0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
2b4e0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2b4f0 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  te3.** CONSTRUCT
2b500 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
2b510 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
2b520 65 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  e an SQL stateme
2b530 6e 74 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  nt, it must firs
2b540 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
2b550 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
2b560 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
2b570 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
2b580 74 69 6e 65 73 2e 20 20 4f 72 2c 20 69 6e 20 6f  tines.  Or, in o
2b590 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 73  ther words, thes
2b5a0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
2b5b0 65 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 20 66  e constructors f
2b5c0 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
2b5d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
2b5e0 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ct..**.** The pr
2b5f0 65 66 65 72 72 65 64 20 72 6f 75 74 69 6e 65 20  eferred routine 
2b600 74 6f 20 75 73 65 20 69 73 20 5b 73 71 6c 69 74  to use is [sqlit
2b610 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2b620 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
2b630 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 69 6e  e3_prepare()] in
2b640 74 65 72 66 61 63 65 20 69 73 20 6c 65 67 61 63  terface is legac
2b650 79 20 61 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  y and should be 
2b660 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 5b 73 71 6c  avoided..** [sql
2b670 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28  ite3_prepare_v3(
2b680 29 5d 20 68 61 73 20 61 6e 20 65 78 74 72 61 20  )] has an extra 
2b690 22 70 72 65 70 46 6c 61 67 73 22 20 6f 70 74 69  "prepFlags" opti
2b6a0 6f 6e 20 74 68 61 74 20 69 73 20 75 73 65 64 0a  on that is used.
2b6b0 2a 2a 20 66 6f 72 20 73 70 65 63 69 61 6c 20 70  ** for special p
2b6c0 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  urposes..**.** T
2b6d0 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 55 54  he use of the UT
2b6e0 46 2d 38 20 69 6e 74 65 72 66 61 63 65 73 20 69  F-8 interfaces i
2b6f0 73 20 70 72 65 66 65 72 72 65 64 2c 20 61 73 20  s preferred, as 
2b700 53 51 4c 69 74 65 20 63 75 72 72 65 6e 74 6c 79  SQLite currently
2b710 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c 20 70 61 72  .** does all par
2b720 73 69 6e 67 20 75 73 69 6e 67 20 55 54 46 2d 38  sing using UTF-8
2b730 2e 20 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e  .  The UTF-16 in
2b740 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
2b750 76 69 64 65 64 0a 2a 2a 20 61 73 20 61 20 63 6f  vided.** as a co
2b760 6e 76 65 6e 69 65 6e 63 65 2e 20 20 54 68 65 20  nvenience.  The 
2b770 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61 63 65  UTF-16 interface
2b780 73 20 77 6f 72 6b 20 62 79 20 63 6f 6e 76 65 72  s work by conver
2b790 74 69 6e 67 20 74 68 65 0a 2a 2a 20 69 6e 70 75  ting the.** inpu
2b7a0 74 20 74 65 78 74 20 69 6e 74 6f 20 55 54 46 2d  t text into UTF-
2b7b0 38 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 69 6e 67  8, then invoking
2b7c0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2b7d0 6e 67 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61  ng UTF-8 interfa
2b7e0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  ce..**.** The fi
2b7f0 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
2b800 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
2b810 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
2b820 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
2b830 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
2b840 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
2b850 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2b860 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2b870 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2b880 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
2b890 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b8a0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
2b8b0 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
2b8c0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
2b8d0 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
2b8e0 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
2b8f0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
2b900 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
2b910 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
2b920 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
2b930 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 2c  lite3_prepare(),
2b940 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b950 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 71  _v2(),.** and sq
2b960 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2b970 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
2b980 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20   use UTF-8, and 
2b990 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b9a0 36 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  6(), sqlite3_pre
2b9b0 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20  pare16_v2(),.** 
2b9c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2b9d0 61 72 65 31 36 5f 76 33 28 29 20 75 73 65 20 55  are16_v3() use U
2b9e0 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
2b9f0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
2ba00 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ent is negative,
2ba10 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
2ba20 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
2ba30 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2ba40 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
2ba50 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68   is positive, th
2ba60 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20  en it is the.** 
2ba70 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2ba80 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
2ba90 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65   ^If nByte is ze
2baa0 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70  ro, then no prep
2bab0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2bac0 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a  t is generated..
2bad0 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  ** If the caller
2bae0 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20   knows that the 
2baf0 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
2bb00 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
2bb10 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65  d, then.** there
2bb20 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66   is a small perf
2bb30 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
2bb40 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20  e to passing an 
2bb50 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
2bb60 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e  that.** is the n
2bb70 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2bb80 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
2bb90 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
2bba0 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
2bbb0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
2bbc0 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e   ^If pzTail is n
2bbd0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a  ot NULL then *pz
2bbe0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
2bbf0 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
2bc00 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20  st byte.** past 
2bc10 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
2bc20 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
2bc30 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
2bc40 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
2bc50 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  .** compile the 
2bc60 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20  first statement 
2bc70 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
2bc80 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
2bc90 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20  ting to.** what 
2bca0 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
2bcb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74  ed..**.** ^*ppSt
2bcc0 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  mt is left point
2bcd0 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65  ing to a compile
2bce0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
2bcf0 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20  ement] that can 
2bd00 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75  be.** executed u
2bd10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  sing [sqlite3_st
2bd20 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72  ep()].  ^If ther
2bd30 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a  e is an error, *
2bd40 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a  ppStmt is set.**
2bd50 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74   to NULL.  ^If t
2bd60 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f  he input text co
2bd70 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69  ntains no SQL (i
2bd80 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61  f the input is a
2bd90 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e  n empty.** strin
2bda0 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20  g or a comment) 
2bdb0 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20  then *ppStmt is 
2bdc0 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20  set to NULL..** 
2bdd0 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63  The calling proc
2bde0 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73  edure is respons
2bdf0 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e  ible for deletin
2be00 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a  g the compiled.*
2be10 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
2be20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2be30 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72  inalize()] after
2be40 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
2be50 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53   with it..** ppS
2be60 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e  tmt may not be N
2be70 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73  ULL..**.** ^On s
2be80 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69  uccess, the sqli
2be90 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61  te3_prepare() fa
2bea0 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73  mily of routines
2beb0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2bec0 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73  OK];.** otherwis
2bed0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
2bee0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
2bef0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2bf00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 2c 20 73  _prepare_v2(), s
2bf10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2bf20 33 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65  3(), sqlite3_pre
2bf30 70 61 72 65 31 36 5f 76 32 28 29 2c 0a 2a 2a 20  pare16_v2(),.** 
2bf40 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2bf50 61 72 65 31 36 5f 76 33 28 29 20 69 6e 74 65 72  are16_v3() inter
2bf60 66 61 63 65 73 20 61 72 65 20 72 65 63 6f 6d 6d  faces are recomm
2bf70 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
2bf80 77 20 70 72 6f 67 72 61 6d 73 2e 0a 2a 2a 20 54  w programs..** T
2bf90 68 65 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  he older interfa
2bfa0 63 65 73 20 28 73 71 6c 69 74 65 33 5f 70 72 65  ces (sqlite3_pre
2bfb0 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
2bfc0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 29 0a  e3_prepare16()).
2bfd0 2a 2a 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ** are retained 
2bfe0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
2bff0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
2c000 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
2c010 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
2c020 6e 20 74 68 65 20 22 76 58 22 20 69 6e 74 65 72  n the "vX" inter
2c030 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
2c040 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2c050 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
2c060 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2c070 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
2c080 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
2c090 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
2c0a0 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
2c0b0 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
2c0c0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
2c0d0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
2c0e0 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
2c0f0 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
2c100 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
2c110 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
2c120 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
2c130 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
2c140 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2c150 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
2c160 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
2c170 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
2c180 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
2c190 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2c1a0 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
2c1b0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
2c1c0 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
2c1d0 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51  . As many as [SQ
2c1e0 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f  LITE_MAX_SCHEMA_
2c1f0 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65  RETRY].** retrie
2c200 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66  s will occur bef
2c210 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ore sqlite3_step
2c220 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20  () gives up and 
2c230 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
2c240 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2c250 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
2c260 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
2c270 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c280 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
2c290 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
2c2a0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
2c2b0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
2c2c0 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
2c2d0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2c2e0 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
2c2f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c300 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
2c310 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
2c320 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
2c330 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
2c340 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
2c350 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
2c360 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
2c370 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2c380 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
2c390 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
2c3a0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
2c3b0 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
2c3c0 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
2c3d0 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
2c3e0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
2c3f0 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
2c400 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
2c410 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
2c420 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
2c430 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
2c440 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
2c450 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
2c460 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
2c470 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
2c480 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
2c490 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
2c4a0 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
2c4b0 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
2c4c0 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
2c4d0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2c4e0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
2c4f0 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
2c500 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
2c510 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
2c520 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
2c530 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
2c540 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
2c550 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
2c560 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
2c570 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
2c580 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
2c590 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
2c5a0 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
2c5b0 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
2c5c0 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
2c5d0 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
2c5e0 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
2c5f0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
2c600 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2c610 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
2c620 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
2c630 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
2c640 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
2c650 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
2c660 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
2c670 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
2c680 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
2c690 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
2c6a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2c6b0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
2c6c0 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
2c6d0 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 6c 69 74 65  **.** <p>^sqlite
2c6e0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20 64  3_prepare_v3() d
2c6f0 69 66 66 65 72 73 20 66 72 6f 6d 20 73 71 6c 69  iffers from sqli
2c700 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2c710 20 6f 6e 6c 79 20 69 6e 20 68 61 76 69 6e 67 0a   only in having.
2c720 2a 2a 20 74 68 65 20 65 78 74 72 61 20 70 72 65  ** the extra pre
2c730 70 46 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72  pFlags parameter
2c740 2c 20 77 68 69 63 68 20 69 73 20 61 20 62 69 74  , which is a bit
2c750 20 61 72 72 61 79 20 63 6f 6e 73 69 73 74 69 6e   array consistin
2c760 67 20 6f 66 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20  g of zero or.** 
2c770 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
2c780 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2c790 49 53 54 45 4e 54 7c 53 51 4c 49 54 45 5f 50 52  ISTENT|SQLITE_PR
2c7a0 45 50 41 52 45 5f 2a 5d 20 66 6c 61 67 73 2e 20  EPARE_*] flags. 
2c7b0 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
2c7c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 69 6e  _prepare_v2() in
2c7d0 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 65 78  terface works ex
2c7e0 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61  actly the same a
2c7f0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
2c800 70 61 72 65 5f 76 33 28 29 20 77 69 74 68 20 61  pare_v3() with a
2c810 20 7a 65 72 6f 20 70 72 65 70 46 6c 61 67 73 20   zero prepFlags 
2c820 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2f 0a 69 6e  parameter..*/.in
2c830 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2c840 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
2c850 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2c860 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2c870 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2c880 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2c890 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2c8a0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2c8b0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2c8c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2c8d0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2c8e0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2c8f0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2c900 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2c910 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2c920 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2c930 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2c940 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2c950 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2c960 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2c970 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
2c980 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
2c990 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2c9a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2c9b0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2c9c0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
2c9d0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2c9e0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
2c9f0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2ca00 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2ca10 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2ca20 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2ca30 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2ca40 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2ca50 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2ca60 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2ca70 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
2ca80 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2ca90 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2caa0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2cab0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
2cac0 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 0a 20  e3_prepare_v3(. 
2cad0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2cae0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2caf0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2cb00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2cb10 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2cb20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2cb30 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2cb40 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2cb50 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2cb60 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2cb70 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75  in bytes. */.  u
2cb80 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70  nsigned int prep
2cb90 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f  Flags, /* Zero o
2cba0 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52  r more SQLITE_PR
2cbb0 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a  EPARE_ flags */.
2cbc0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2cbd0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2cbe0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2cbf0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2cc00 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
2cc10 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2cc20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2cc30 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2cc40 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2cc50 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
2cc60 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2cc70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2cc80 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2cc90 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2cca0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2ccb0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2ccc0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2ccd0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2cce0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2ccf0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2cd00 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2cd10 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2cd20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2cd30 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2cd40 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2cd50 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2cd60 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2cd70 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2cd80 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2cd90 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
2cda0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2cdb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
2cdc0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
2cdd0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
2cde0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
2cdf0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
2ce00 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
2ce10 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2ce20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2ce30 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2ce40 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2ce50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2ce60 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2ce70 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2ce80 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2ce90 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
2cea0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2ceb0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2cec0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2ced0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2cee0 72 65 31 36 5f 76 33 28 0a 20 20 73 71 6c 69 74  re16_v3(.  sqlit
2cef0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
2cf00 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
2cf10 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2cf20 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
2cf30 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
2cf40 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
2cf50 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
2cf60 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
2cf70 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
2cf80 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
2cf90 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e  tes. */.  unsign
2cfa0 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67 73  ed int prepFlags
2cfb0 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72  , /* Zero or mor
2cfc0 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45  e SQLITE_PREPARE
2cfd0 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c  _ flags */.  sql
2cfe0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2cff0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2d000 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2d010 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2d020 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2d030 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2d040 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2d050 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
2d060 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
2d070 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
2d080 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   SQL.** METHOD: 
2d090 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2d0a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d0b0 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65  sql(P) interface
2d0c0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2d0d0 65 72 20 74 6f 20 61 20 63 6f 70 79 20 6f 66 20  er to a copy of 
2d0e0 74 68 65 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c  the UTF-8.** SQL
2d0f0 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72   text used to cr
2d100 65 61 74 65 20 5b 70 72 65 70 61 72 65 64 20 73  eate [prepared s
2d110 74 61 74 65 6d 65 6e 74 5d 20 50 20 69 66 20 50  tatement] P if P
2d120 20 77 61 73 0a 2a 2a 20 63 72 65 61 74 65 64 20   was.** created 
2d130 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
2d140 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
2d150 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
2d160 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
2d170 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20  repare16_v2()], 
2d180 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2d190 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20  are16_v3()]..** 
2d1a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70  ^The sqlite3_exp
2d1b0 61 6e 64 65 64 5f 73 71 6c 28 50 29 20 69 6e 74  anded_sql(P) int
2d1c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2d1d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 55 54   pointer to a UT
2d1e0 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  F-8.** string co
2d1f0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 53 51 4c  ntaining the SQL
2d200 20 74 65 78 74 20 6f 66 20 70 72 65 70 61 72 65   text of prepare
2d210 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 77 69  d statement P wi
2d220 74 68 0a 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72  th.** [bound par
2d230 61 6d 65 74 65 72 73 5d 20 65 78 70 61 6e 64 65  ameters] expande
2d240 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
2d250 78 61 6d 70 6c 65 2c 20 69 66 20 61 20 70 72 65  xample, if a pre
2d260 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2d270 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
2d280 20 74 68 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74   the SQL.** text
2d290 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78   "SELECT $abc,:x
2d2a0 79 7a 22 20 61 6e 64 20 69 66 20 70 61 72 61 6d  yz" and if param
2d2b0 65 74 65 72 20 24 61 62 63 20 69 73 20 62 6f 75  eter $abc is bou
2d2c0 6e 64 20 74 6f 20 69 6e 74 65 67 65 72 20 32 33  nd to integer 23
2d2d0 34 35 0a 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65  45.** and parame
2d2e0 74 65 72 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f  ter :xyz is unbo
2d2f0 75 6e 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  und, then sqlite
2d300 33 5f 73 71 6c 28 29 20 77 69 6c 6c 20 72 65 74  3_sql() will ret
2d310 75 72 6e 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  urn.** the origi
2d320 6e 61 6c 20 73 74 72 69 6e 67 2c 20 22 53 45 4c  nal string, "SEL
2d330 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 62  ECT $abc,:xyz" b
2d340 75 74 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  ut sqlite3_expan
2d350 64 65 64 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c  ded_sql().** wil
2d360 6c 20 72 65 74 75 72 6e 20 22 53 45 4c 45 43 54  l return "SELECT
2d370 20 32 33 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a   2345,NULL".)^.*
2d380 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d390 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2d3a0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2d3b0 6e 73 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66  ns NULL if insuf
2d3c0 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a  ficient memory.*
2d3d0 2a 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 74  * is available t
2d3e0 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
2d3f0 74 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 73  t, or if the res
2d400 75 6c 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64  ult would exceed
2d410 20 74 68 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69   the.** the maxi
2d420 6d 75 6d 20 73 74 72 69 6e 67 20 6c 65 6e 67 74  mum string lengt
2d430 68 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  h determined by 
2d440 74 68 65 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  the [SQLITE_LIMI
2d450 54 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a  T_LENGTH]..**.**
2d460 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52   ^The [SQLITE_TR
2d470 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20  ACE_SIZE_LIMIT] 
2d480 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2d490 69 6f 6e 20 6c 69 6d 69 74 73 20 74 68 65 20 73  ion limits the s
2d4a0 69 7a 65 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20  ize of.** bound 
2d4b0 70 61 72 61 6d 65 74 65 72 20 65 78 70 61 6e 73  parameter expans
2d4c0 69 6f 6e 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c  ions.  ^The [SQL
2d4d0 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20  ITE_OMIT_TRACE] 
2d4e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
2d4f0 6f 70 74 69 6f 6e 20 63 61 75 73 65 73 20 73 71  option causes sq
2d500 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2d510 71 6c 28 29 20 74 6f 20 61 6c 77 61 79 73 20 72  ql() to always r
2d520 65 74 75 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  eturn NULL..**.*
2d530 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72 65  * ^The string re
2d540 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2d550 33 5f 73 71 6c 28 50 29 20 69 73 20 6d 61 6e 61  3_sql(P) is mana
2d560 67 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 6e  ged by SQLite an
2d570 64 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  d is.** automati
2d580 63 61 6c 6c 79 20 66 72 65 65 64 20 77 68 65 6e  cally freed when
2d590 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2d5a0 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2d5b0 69 7a 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74  ized..** ^The st
2d5c0 72 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79  ring returned by
2d5d0 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2d5e0 64 5f 73 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65  d_sql(P), on the
2d5f0 20 6f 74 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20   other hand,.** 
2d600 69 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  is obtained from
2d610 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2d620 28 29 5d 20 61 6e 64 20 6d 75 73 74 20 62 65 20  ()] and must be 
2d630 66 72 65 65 20 62 79 20 74 68 65 20 61 70 70 6c  free by the appl
2d640 69 63 61 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61  ication.** by pa
2d650 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
2d660 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f  ite3_free()]..*/
2d670 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
2d680 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
2d690 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 63  _stmt *pStmt);.c
2d6a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 78 70  har *sqlite3_exp
2d6b0 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 74 65  anded_sql(sqlite
2d6c0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2d6d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d6e0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
2d6f0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
2d700 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
2d710 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  se.** METHOD: sq
2d720 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2d730 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2d740 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
2d750 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2d760 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
2d770 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
2d780 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
2d790 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
2d7a0 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
2d7b0 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
2d7c0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2d7d0 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
2d7e0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
2d7f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2d800 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2d810 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
2d820 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
2d830 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2d840 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
2d850 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
2d860 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
2d870 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
2d880 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
2d890 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
2d8a0 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
2d8b0 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2d8c0 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
2d8d0 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
2d8e0 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
2d8f0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2d900 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
2d910 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
2d920 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
2d930 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
2d940 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
2d950 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
2d960 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
2d970 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
2d980 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
2d990 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2d9a0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
2d9b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2d9c0 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
2d9d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2d9e0 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
2d9f0 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
2da00 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
2da10 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
2da20 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
2da30 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
2da40 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
2da50 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
2da60 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
2da70 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
2da80 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
2da90 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
2daa0 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
2dab0 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
2dac0 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
2dad0 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
2dae0 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
2daf0 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
2db00 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
2db10 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
2db20 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
2db30 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
2db40 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
2db50 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
2db60 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
2db70 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2db80 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
2db90 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
2dba0 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
2dbb0 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
2dbc0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
2dbd0 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
2dbe0 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
2dbf0 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
2dc00 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
2dc10 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
2dc20 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
2dc30 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  disk..** ^The sq
2dc40 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2dc50 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  nly() interface 
2dc60 72 65 74 75 72 6e 73 20 74 72 75 65 20 66 6f 72  returns true for
2dc70 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 65 0a 2a   [BEGIN] since.*
2dc80 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 65 6c 79  * [BEGIN] merely
2dc90 20 73 65 74 73 20 69 6e 74 65 72 6e 61 6c 20 66   sets internal f
2dca0 6c 61 67 73 2c 20 62 75 74 20 74 68 65 20 5b 42  lags, but the [B
2dcb0 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d 4d 45 44  EGIN|BEGIN IMMED
2dcc0 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45  IATE] and.** [BE
2dcd0 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 4c 55 53  GIN|BEGIN EXCLUS
2dce0 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 20 64 6f  IVE] commands do
2dcf0 20 74 6f 75 63 68 20 74 68 65 20 64 61 74 61 62   touch the datab
2dd00 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a 20 73 71  ase and so.** sq
2dd10 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2dd20 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 20 66 61  nly() returns fa
2dd30 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 20 63 6f  lse for those co
2dd40 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73  mmands..*/.int s
2dd50 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2dd60 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
2dd70 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2dd80 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
2dd90 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
2dda0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
2ddb0 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20  s Been Reset.** 
2ddc0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2ddd0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2dde0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2ddf0 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(S) interface r
2de00 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
2de10 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a  -zero) if the.**
2de20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2de30 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e  ment] S has been
2de40 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73   stepped at leas
2de50 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a  t once using .**
2de60 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2de70 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74 68  )] but has neith
2de80 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65  er run to comple
2de90 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a  tion (returned.*
2dea0 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20  * [SQLITE_DONE] 
2deb0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74  from [sqlite3_st
2dec0 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62  ep(S)]) nor.** b
2ded0 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
2dee0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2def0 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
2df00 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
2df10 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2df20 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
2df30 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2df40 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
2df50 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
2df60 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
2df70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
2df80 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
2df90 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2dfa0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2dfb0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2dfc0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
2dfd0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
2dfe0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
2dff0 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
2e000 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
2e010 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
2e020 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
2e030 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
2e040 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
2e050 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
2e060 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
2e070 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
2e080 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
2e090 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
2e0a0 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
2e0b0 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
2e0c0 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
2e0d0 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
2e0e0 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
2e0f0 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
2e100 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
2e110 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  open..*/.int sql
2e120 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
2e130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2e140 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e150 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
2e160 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
2e170 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
2e180 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2e190 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
2e1a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e1b0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
2e1c0 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
2e1d0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
2e1e0 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
2e1f0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
2e200 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
2e210 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
2e220 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2e230 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
2e240 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
2e250 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
2e260 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
2e270 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e280 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
2e290 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
2e2a0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
2e2b0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
2e2c0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
2e2d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e2e0 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
2e2f0 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
2e300 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
2e310 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
2e320 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
2e330 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e340 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
2e350 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
2e360 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
2e370 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
2e380 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2e390 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
2e3a0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
2e3b0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
2e3c0 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
2e3d0 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
2e3e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
2e3f0 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
2e400 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2e410 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  lue.  The.** [sq
2e420 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2e430 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
2e440 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73   be used to cons
2e450 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20  truct a new .** 
2e460 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e470 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20  3_value from an 
2e480 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2e490 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
2e4a0 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
2e4b0 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
2e4c0 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
2e4d0 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
2e4e0 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
2e4f0 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
2e500 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
2e510 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
2e520 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2e530 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
2e540 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2e550 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
2e560 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2e570 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
2e580 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
2e590 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
2e5a0 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
2e5b0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
2e5c0 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
2e5d0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2e5e0 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
2e5f0 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
2e600 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
2e610 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
2e620 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
2e630 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2e640 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
2e650 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
2e660 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
2e670 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
2e680 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2e690 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2e6a0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2e6b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2e6c0 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
2e6d0 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
2e6e0 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
2e6f0 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
2e700 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
2e710 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
2e720 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
2e730 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
2e740 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
2e750 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2e760 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2e770 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2e780 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
2e790 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
2e7a0 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
2e7b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e7c0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e7d0 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
2e7e0 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
2e7f0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
2e800 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
2e810 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2e820 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2e830 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
2e840 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e850 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
2e860 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2e870 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2e880 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
2e890 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
2e8a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2e8b0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
2e8c0 6c 79 20 62 65 20 75 73 65 64 20 61 73 20 61 72  ly be used as ar
2e8d0 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 5b 73  guments.** to [s
2e8e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2e8f0 6c 75 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lue()], [sqlite3
2e900 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2c 20  _bind_value()], 
2e910 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2e920 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 0a 2a 2a  value_dup()]..**
2e930 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2e940 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
2e950 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
2e960 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
2e970 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2e980 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2e990 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e9a0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2e9b0 75 63 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  uct sqlite3_valu
2e9c0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  e sqlite3_value;
2e9d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e9e0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
2e9f0 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
2ea00 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
2ea10 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
2ea20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
2ea30 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
2ea40 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
2ea50 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
2ea60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
2ea70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2ea80 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
2ea90 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
2eaa0 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
2eab0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2eac0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
2ead0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2eae0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2eaf0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2eb00 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
2eb10 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
2eb20 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
2eb30 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
2eb40 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
2eb50 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
2eb60 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2eb70 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
2eb80 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2eb90 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2eba0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2ebb0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
2ebc0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
2ebd0 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
2ebe0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
2ebf0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2ec00 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
2ec10 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
2ec20 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
2ec30 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
2ec40 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
2ec50 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
2ec60 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
2ec70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
2ec80 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
2ec90 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2eca0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2ecb0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
2ecc0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
2ecd0 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
2ece0 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ng}.** METHOD: s
2ecf0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2ed00 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
2ed10 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
2ed20 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
2ed30 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2ed40 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
2ed50 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
2ed60 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
2ed70 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
2ed80 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
2ed90 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
2eda0 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
2edb0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
2edc0 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
2edd0 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
2ede0 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
2edf0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
2ee00 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
2ee10 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
2ee20 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
2ee30 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
2ee40 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
2ee50 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
2ee60 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
2ee70 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
2ee80 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
2ee90 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
2eea0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
2eeb0 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
2eec0 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
2eed0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
2eee0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
2eef0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2ef00 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
2ef10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2ef20 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2ef30 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2ef40 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
2ef50 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
2ef60 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
2ef70 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
2ef80 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
2ef90 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2efa0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
2efb0 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
2efc0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
2efd0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2efe0 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
2eff0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
2f000 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
2f010 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
2f020 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2f030 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
2f040 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
2f050 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
2f060 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
2f070 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
2f080 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
2f090 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
2f0a0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
2f0b0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
2f0c0 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
2f0d0 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
2f0e0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
2f0f0 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
2f100 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
2f110 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2f120 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
2f130 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
2f140 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
2f150 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
2f160 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
2f170 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
2f180 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
2f190 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
2f1a0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
2f1b0 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
2f1c0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2f1d0 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
2f1e0 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
2f1f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2f200 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2f210 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
2f220 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2f230 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
2f240 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2f250 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2f260 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
2f270 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
2f280 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2f290 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c  blob() is a NULL
2f2a0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
2f2b0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2f2c0 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64  er.** is ignored
2f2d0 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73   and the end res
2f2e0 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20  ult is the same 
2f2f0 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  as sqlite3_bind_
2f300 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  null()..**.** ^(
2f310 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
2f320 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
2f330 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
2f340 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
2f350 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2f360 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
2f370 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
2f380 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
2f390 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2f3a0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
2f3b0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
2f3c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2f3d0 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
2f3e0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2f3f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2f400 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2f410 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2f420 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
2f430 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
2f440 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
2f450 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
2f460 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2f470 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2f480 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2f490 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
2f4a0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2f4b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2f4c0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
2f4d0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
2f4e0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2f4f0 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
2f500 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
2f510 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
2f520 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
2f530 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
2f540 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2f550 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74  ext16() or sqlit
2f560 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2f570 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61   then.** that pa
2f580 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
2f590 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
2f5a0 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
2f5b0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
2f5c0 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
2f5d0 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
2f5e0 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
2f5f0 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
2f600 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
2f610 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
2f620 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
2f630 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2f640 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2f650 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2f660 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
2f670 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
2f680 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
2f690 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
2f6a0 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
2f6b0 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
2f6c0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
2f6d0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
2f6e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
2f6f0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
2f700 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e  e BLOB and strin
2f710 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66  g binding interf
2f720 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73  aces.** is a des
2f730 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
2f740 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2f750 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
2f760 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
2f770 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2f780 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
2f790 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
2f7a0 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
2f7b0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
2f7c0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
2f7d0 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20  all to bind API 
2f7e0 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  fails..** ^If th
2f7f0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2f800 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
2f810 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
2f820 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
2f830 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
2f840 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
2f850 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
2f860 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
2f870 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
2f880 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
2f890 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
2f8a0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
2f8b0 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
2f8c0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
2f8d0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
2f8e0 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
2f8f0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2f900 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
2f910 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
2f920 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2f930 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2f940 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ..**.** ^The six
2f950 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2f960 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2f970 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  64() must be one
2f980 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   of.** [SQLITE_U
2f990 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
2f9a0 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
2f9b0 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
2f9c0 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74  TE_UTF16LE].** t
2f9d0 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e  o specify the en
2f9e0 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65  coding of the te
2f9f0 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  xt in the third 
2fa00 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a  parameter.  If.*
2fa10 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75  * the sixth argu
2fa20 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2fa30 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73  bind_text64() is
2fa40 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
2fa50 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65  ** allowed value
2fa60 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f  s shown above, o
2fa70 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e  r if the text en
2fa80 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2fa90 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ent.** from the 
2faa0 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
2fab0 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20  ed by the sixth 
2fac0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
2fad0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2fae0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2faf0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2fb00 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
2fb10 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
2fb20 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
2fb30 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
2fb40 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
2fb50 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
2fb60 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
2fb70 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
2fb80 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
2fb90 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
2fba0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
2fbb0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
2fbc0 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
2fbd0 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
2fbe0 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
2fbf0 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
2fc00 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
2fc10 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
2fc20 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2fc30 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
2fc40 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
2fc50 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
2fc60 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
2fc70 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
2fc80 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
2fc90 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
2fca0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2fcb0 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72  te3_bind_pointer
2fcc0 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72 6f 75 74  (S,I,P,T,D) rout
2fcd0 69 6e 65 20 63 61 75 73 65 73 20 74 68 65 20 49  ine causes the I
2fce0 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 6e  -th parameter in
2fcf0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2fd00 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20 68 61  atement] S to ha
2fd10 76 65 20 61 6e 20 53 51 4c 20 76 61 6c 75 65 20  ve an SQL value 
2fd20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20 74 6f 20  of NULL, but to 
2fd30 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73 73 6f 63  also be.** assoc
2fd40 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
2fd50 6f 69 6e 74 65 72 20 50 20 6f 66 20 74 79 70 65  ointer P of type
2fd60 20 54 2e 20 20 5e 44 20 69 73 20 65 69 74 68 65   T.  ^D is eithe
2fd70 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
2fd80 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72   or.** a pointer
2fd90 20 74 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72   to a destructor
2fda0 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 50 2e   function for P.
2fdb0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e   ^SQLite will in
2fdc0 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64 65 73 74  voke the.** dest
2fdd0 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 61 20  ructor D with a 
2fde0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
2fdf0 6f 66 20 50 20 77 68 65 6e 20 69 74 20 69 73 20  of P when it is 
2fe00 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 0a 2a  finished using.*
2fe10 2a 20 50 2e 20 20 54 68 65 20 54 20 70 61 72 61  * P.  The T para
2fe20 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20  meter should be 
2fe30 61 20 73 74 61 74 69 63 20 73 74 72 69 6e 67 2c  a static string,
2fe40 20 70 72 65 66 65 72 61 62 6c 79 20 61 20 73 74   preferably a st
2fe50 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72 61 6c 2e  ring.** literal.
2fe60 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   The sqlite3_bin
2fe70 64 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f 75 74  d_pointer() rout
2fe80 69 6e 65 20 69 73 20 70 61 72 74 20 6f 66 20 74  ine is part of t
2fe90 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65 72 20 70  he.** [pointer p
2fea0 61 73 73 69 6e 67 20 69 6e 74 65 72 66 61 63 65  assing interface
2feb0 5d 20 61 64 64 65 64 20 66 6f 72 20 53 51 4c 69  ] added for SQLi
2fec0 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a 0a 2a 2a  te 3.20.0..**.**
2fed0 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
2fee0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2fef0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2ff00 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
2ff10 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
2ff20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2ff30 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
2ff40 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2ff50 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
2ff60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2ff70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
2ff80 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
2ff90 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
2ffa0 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
2ffb0 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
2ffc0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
2ffd0 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
2ffe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
2fff0 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
30000 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
30010 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
30020 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
30030 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
30040 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
30050 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
30060 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
30070 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
30080 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
30090 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
300a0 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
300b0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
300c0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
300d0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
300e0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
300f0 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
30100 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
30110 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
30120 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
30130 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
30140 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
30150 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74  TE_TOOBIG] might
30160 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
30170 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74  the size of a st
30180 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20  ring or BLOB.** 
30190 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69  exceeds limits i
301a0 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  mposed by [sqlit
301b0 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
301c0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29  E_LIMIT_LENGTH])
301d0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d   or.** [SQLITE_M
301e0 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e  AX_LENGTH]..** ^
301f0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
30200 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
30210 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
30220 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
30230 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
30240 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
30250 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
30260 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
30270 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
30280 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
30290 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
302a0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
302b0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
302c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
302d0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
302e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
302f0 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
30300 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
30310 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
30320 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
30330 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
30340 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69  bind_blob64(sqli
30350 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
30360 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c  const void*, sql
30370 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
30380 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30390 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
303a0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
303b0 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
303c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
303d0 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
303e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
303f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30400 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
30410 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
30420 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30430 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
30440 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
30450 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
30460 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
30470 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
30480 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
30490 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  mt*,int,const ch
304a0 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28  ar*,int,void(*)(
304b0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
304c0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
304d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
304e0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
304f0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
30500 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
30510 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
30520 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30530 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
30540 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
30550 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
30560 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
30570 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e  )(void*), unsign
30580 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67  ed char encoding
30590 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
305a0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
305b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
305c0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
305d0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
305e0 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 73 71  _bind_pointer(sq
305f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30600 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  , void*, const c
30610 68 61 72 2a 2c 76 6f 69 64 28 2a 29 28 76 6f 69  har*,void(*)(voi
30620 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
30630 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
30640 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30650 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20  nt, int n);.int 
30660 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
30670 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  oblob64(sqlite3_
30680 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
30690 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a  te3_uint64);../*
306a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
306b0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
306c0 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44  meters.** METHOD
306d0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
306e0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
306f0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
30700 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
30710 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
30720 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
30730 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30740 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
30750 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
30760 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
30770 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
30780 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
30790 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
307a0 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
307b0 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
307c0 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
307d0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
307e0 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
307f0 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
30800 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
30810 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
30820 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
30830 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
30840 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
30850 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
30860 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
30870 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
30880 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
30890 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
308a0 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
308b0 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
308c0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
308d0 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
308e0 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
308f0 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
30900 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
30910 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
30920 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
30930 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [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 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
30960 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
30970 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
30980 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
30990 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
309a0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
309b0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
309c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
309d0 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
309e0 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meter.** METHOD:
309f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30a00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30a10 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30a20 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
30a30 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
30a40 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
30a50 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
30a60 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
30a70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30a80 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
30a90 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
30aa0 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
30ab0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
30ac0 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
30ad0 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
30ae0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
30af0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
30b00 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
30b10 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
30b20 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
30b30 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
30b40 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
30b50 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
30b60 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
30b70 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
30b80 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
30b90 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
30ba0 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
30bb0 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
30bc0 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
30bd0 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
30be0 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
30bf0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
30c00 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
30c10 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
30c20 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
30c30 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
30c40 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
30c50 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
30c60 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
30c70 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
30c80 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
30c90 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
30ca0 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
30cb0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
30cc0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
30cd0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
30ce0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
30cf0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
30d00 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
30d10 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
30d20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30d30 65 31 36 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  e16()],.** [sqli
30d40 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
30d50 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
30d60 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
30d70 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
30d80 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
30d90 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
30da0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
30db0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30dc0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
30dd0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
30de0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
30df0 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
30e00 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
30e10 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
30e20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30e30 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
30e40 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
30e50 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
30e60 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d   Given Name.** M
30e70 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
30e80 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  tmt.**.** ^Retur
30e90 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
30ea0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
30eb0 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
30ec0 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
30ed0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
30ee0 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
30ef0 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
30f00 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
30f10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
30f20 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
30f30 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
30f40 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
30f50 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
30f60 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
30f70 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
30f80 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
30f90 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
30fa0 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
30fb0 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
30fc0 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
30fd0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
30fe0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
30ff0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 0a  pare16_v2()] or.
31000 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
31010 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a  are16_v3()]..**.
31020 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
31030 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
31040 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
31050 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
31060 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
31070 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
31080 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
31090 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f  eter_name()]..*/
310a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
310b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
310c0 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
310d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
310e0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
310f0 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
31100 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
31110 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
31120 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31130 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
31140 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
31150 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
31160 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
31170 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
31180 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
31190 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
311a0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
311b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
311c0 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
311d0 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
311e0 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
311f0 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
31200 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
31210 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
31220 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
31230 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
31240 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
31250 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
31260 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
31270 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
31280 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
31290 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
312a0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
312b0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
312c0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
312d0 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73  ement]. ^If this
312e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
312f0 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74   0, that means t
31300 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  he .** [prepared
31310 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65 74 75   statement] retu
31320 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66 6f 72  rns no data (for
31330 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
31340 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76  ATE])..** ^Howev
31350 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75 73 65  er, just because
31360 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
31370 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65  turns a positive
31380 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74   number does not
31390 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e  .** mean that on
313a0 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f  e or more rows o
313b0 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65 20 72  f data will be r
313c0 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c  eturned.  ^A SEL
313d0 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  ECT statement.**
313e0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68 61 76   will always hav
313f0 65 20 61 20 70 6f 73 69 74 69 76 65 20 73 71 6c  e a positive sql
31400 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
31410 74 28 29 20 62 75 74 20 64 65 70 65 6e 64 69 6e  t() but dependin
31420 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52  g on the.** WHER
31430 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61  E clause constra
31440 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74 61 62  ints and the tab
31450 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d  le content, it m
31460 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f 20 72  ight return no r
31470 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ows..**.** See a
31480 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
31490 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  ta_count()].*/.i
314a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
314b0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
314c0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
314d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
314e0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
314f0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
31500 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
31510 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
31520 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
31530 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
31540 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
31550 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
31560 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
31570 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
31580 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
31590 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
315a0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
315b0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
315c0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
315d0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
315e0 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
315f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
31600 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
31610 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
31620 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
31630 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
31640 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
31650 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
31660 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
31670 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
31680 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
31690 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
316a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
316b0 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
316c0 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
316d0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
316e0 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
316f0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
31700 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
31710 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
31720 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
31730 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
31740 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
31750 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
31760 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
31770 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
31780 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
31790 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
317a0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
317b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
317c0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
317d0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
317e0 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
317f0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
31800 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
31810 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
31820 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
31830 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
31840 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
31850 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
31860 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
31870 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
31880 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
31890 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
318a0 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
318b0 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
318c0 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
318d0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
318e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
318f0 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
31900 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
31910 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
31920 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
31930 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
31940 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
31950 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
31960 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
31970 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
31980 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
31990 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
319a0 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
319b0 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
319c0 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
319d0 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  next..*/.const c
319e0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
319f0 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
31a00 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
31a10 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
31a20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
31a30 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
31a40 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
31a50 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
31a60 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
31a70 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45  ery Result.** ME
31a80 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
31a90 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
31aa0 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
31ab0 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
31ac0 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
31ad0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
31ae0 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
31af0 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
31b00 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
31b10 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
31b20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
31b30 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
31b40 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
31b50 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
31b60 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
31b70 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
31b80 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
31b90 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
31ba0 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
31bb0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
31bc0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
31bd0 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
31be0 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
31bf0 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
31c00 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
31c10 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
31c20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
31c30 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
31c40 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
31c50 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
31c60 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
31c70 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
31c80 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
31c90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
31ca0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
31cb0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
31cc0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
31cd0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
31ce0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
31cf0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
31d00 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
31d10 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
31d20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
31d30 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
31d40 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
31d50 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
31d60 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
31d70 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
31d80 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
31d90 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
31da0 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
31db0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
31dc0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
31dd0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
31de0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
31df0 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
31e00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
31e10 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
31e20 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
31e30 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
31e40 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
31e50 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
31e60 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
31e70 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
31e80 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
31e90 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
31ea0 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
31eb0 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
31ec0 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
31ed0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
31ee0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
31ef0 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
31f00 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
31f10 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
31f20 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
31f30 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
31f40 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
31f50 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
31f60 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
31f70 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
31f80 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
31f90 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
31fa0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
31fb0 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
31fc0 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
31fd0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
31fe0 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
31ff0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
32000 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
32010 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
32020 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
32030 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
32040 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
32050 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
32060 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
32070 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
32080 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
32090 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
320a0 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
320b0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
320c0 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
320d0 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
320e0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
320f0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
32100 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
32110 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
32120 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
32130 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
32140 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
32150 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
32160 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
32170 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
32180 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
32190 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
321a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
321b0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
321c0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
321d0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
321e0 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
321f0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
32200 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
32210 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
32220 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
32230 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
32240 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
32250 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
32260 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
32270 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32280 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
32290 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
322a0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
322b0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
322c0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
322d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
322e0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
322f0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
32300 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
32310 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
32320 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
32330 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
32340 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
32350 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
32360 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
32370 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
32380 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
32390 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
323a0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
323b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
323c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
323d0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
323e0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
323f0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
32400 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
32410 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
32420 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32430 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
32440 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
32450 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
32460 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54  ry Result.** MET
32470 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
32480 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
32490 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
324a0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
324b0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
324c0 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
324d0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
324e0 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
324f0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
32500 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
32510 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
32520 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
32530 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
32540 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
32550 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
32560 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
32570 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
32580 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
32590 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
325a0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
325b0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
325c0 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
325d0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
325e0 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
325f0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
32600 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
32610 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
32620 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
32630 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
32640 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
32650 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
32660 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
32670 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
32680 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
32690 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
326a0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
326b0 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
326c0 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
326d0 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
326e0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
326f0 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
32700 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
32710 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
32720 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
32730 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
32740 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
32750 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
32760 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
32770 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
32780 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
32790 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
327a0 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
327b0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
327c0 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
327d0 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
327e0 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
327f0 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
32800 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
32810 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
32820 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
32830 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
32840 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
32850 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
32860 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
32870 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
32880 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
32890 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
328a0 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
328b0 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
328c0 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
328d0 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
328e0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
328f0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
32900 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32910 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
32920 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
32930 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
32940 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
32950 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32960 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
32970 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54  Statement.** MET
32980 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
32990 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
329a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
329b0 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
329c0 65 70 61 72 65 64 20 75 73 69 6e 67 20 61 6e 79  epared using any
329d0 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
329e0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
329f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
32a00 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v3()], [sqlite3_
32a10 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c  prepare16_v2()],
32a20 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
32a30 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d 20  prepare16_v3()] 
32a40 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
32a50 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
32a60 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
32a70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
32a80 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
32a90 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
32aa0 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
32ab0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
32ac0 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
32ad0 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
32ae0 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
32af0 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
32b00 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
32b10 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
32b20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
32b30 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
32b40 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
32b50 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
32b60 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 0a  "vX" interfaces.
32b70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
32b80 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69  are_v3()], [sqli
32b90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
32ba0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
32bb0 61 72 65 31 36 5f 76 33 28 29 5d 2c 0a 2a 2a 20  are16_v3()],.** 
32bc0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
32bd0 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
32be0 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
32bf0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
32c00 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
32c10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
32c20 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
32c30 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
32c40 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 20   "vX" interface 
32c50 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
32c60 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
32c70 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
32c80 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
32c90 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
32ca0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
32cb0 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
32cc0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
32cd0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
32ce0 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
32cf0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
32d00 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
32d10 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
32d20 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
32d30 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
32d40 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
32d50 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
32d60 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
32d70 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
32d80 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
32d90 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
32da0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
32db0 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
32dc0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
32dd0 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
32de0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
32df0 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
32e00 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
32e10 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
32e20 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
32e30 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
32e40 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
32e50 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
32e60 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
32e70 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
32e80 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
32e90 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
32ea0 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
32eb0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
32ec0 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
32ed0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
32ee0 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
32ef0 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
32f00 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
32f10 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
32f20 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
32f30 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
32f40 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
32f50 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
32f60 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
32f70 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
32f80 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
32f90 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
32fa0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
32fb0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
32fc0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
32fd0 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
32fe0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
32ff0 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
33000 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
33010 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
33020 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
33030 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
33040 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
33050 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
33060 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
33070 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
33080 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
33090 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
330a0 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
330b0 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
330c0 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
330d0 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
330e0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
330f0 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
33100 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
33110 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
33120 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
33130 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
33140 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
33150 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
33160 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
33170 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
33180 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
33190 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
331a0 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
331b0 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
331c0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
331d0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
331e0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
331f0 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
33200 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
33210 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
33220 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
33230 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
33240 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
33250 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
33260 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
33270 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
33280 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
33290 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
332a0 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
332b0 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
332c0 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
332d0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
332e0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
332f0 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
33300 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
33310 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
33320 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
33330 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
33340 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
33350 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
33360 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
33370 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
33380 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
33390 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
333a0 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
333b0 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
333c0 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
333d0 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
333e0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
333f0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
33400 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
33410 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
33420 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
33430 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
33440 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
33450 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
33460 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
33470 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
33480 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
33490 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
334a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
334b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
334c0 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
334d0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
334e0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
334f0 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
33500 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
33510 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
33520 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
33530 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
33540 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
33550 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
33560 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
33570 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
33580 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
33590 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
335a0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
335b0 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
335c0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
335d0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
335e0 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
335f0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
33600 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
33610 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
33620 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
33630 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
33640 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
33650 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
33660 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
33670 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e  fter [version 3.
33680 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66  6.23.1] ([dateof
33690 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73  :3.6.23.1],.** s
336a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
336b0 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
336c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
336d0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
336e0 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
336f0 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
33700 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
33710 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
33720 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
33730 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
33740 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
33750 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
33760 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
33770 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
33780 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
33790 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
337a0 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
337b0 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
337c0 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
337d0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
337e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
337f0 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
33800 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
33810 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
33820 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
33830 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
33840 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
33850 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
33860 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
33870 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
33880 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
33890 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
338a0 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
338b0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
338c0 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
338d0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
338e0 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
338f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
33900 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
33910 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
33920 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
33930 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
33940 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
33950 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
33960 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
33970 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
33980 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
33990 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
339a0 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
339b0 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
339c0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
339d0 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
339e0 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
339f0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
33a00 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
33a10 72 65 70 61 72 65 5f 76 33 28 29 5d 20 6f 72 20  repare_v3()] or 
33a20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33a30 5f 76 32 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  _v2()].** or [sq
33a40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
33a50 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
33a60 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29  3_prepare16_v3()
33a70 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
33a80 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
33a90 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
33aa0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
33ab0 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
33ac0 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
33ad0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
33ae0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
33af0 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
33b00 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
33b10 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
33b20 65 20 6f 66 20 74 68 65 20 22 76 58 22 20 69 6e  e of the "vX" in
33b30 74 65 72 66 61 63 65 73 20 69 73 20 72 65 63 6f  terfaces is reco
33b40 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20  mmended..*/.int 
33b50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
33b60 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
33b70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
33b80 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
33b90 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
33ba0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
33bb0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
33bc0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
33bd0 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
33be0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
33bf0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
33c00 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
33c10 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
33c20 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
33c30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33c40 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
33c50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
33c60 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
33c70 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
33c80 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
33c90 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
33ca0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
33cb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33cc0 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
33cd0 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
33ce0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
33cf0 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
33d00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
33d10 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
33d20 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
33d30 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
33d40 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68   pointer..** ^Th
33d50 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
33d60 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
33d70 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65  returns 0 if the
33d80 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
33d90 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
33da0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20  ep](P) returned 
33db0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
33dc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
33dd0 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69  a_count(P).** wi
33de0 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65  ll return non-ze
33df0 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63  ro if previous c
33e00 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
33e10 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
33e20 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57  d.** [SQLITE_ROW
33e30 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65  ], except in the
33e40 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52   case of the [PR
33e50 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c  AGMA incremental
33e60 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72  _vacuum].** wher
33e70 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  e it always retu
33e80 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65  rns zero since e
33e90 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74  ach step of that
33ea0 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70   multi-step.** p
33eb0 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20  ragma returns 0 
33ec0 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e  columns of data.
33ed0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
33ee0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
33ef0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
33f00 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
33f10 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
33f20 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
33f30 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
33f40 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
33f50 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
33f60 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
33f70 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
33f80 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
33f90 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
33fa0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
33fb0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
33fc0 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
33fd0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
33fe0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
33ff0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
34000 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
34010 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
34020 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
34030 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
34040 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
34050 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
34060 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
34070 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
34080 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
34090 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
340a0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
340b0 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
340c0 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
340d0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
340e0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
340f0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
34100 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
34110 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
34120 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
34130 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
34140 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
34150 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
34160 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
34170 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
34180 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
34190 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
341a0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
341b0 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
341c0 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
341d0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
341e0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
341f0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
34200 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
34210 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
34220 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
34230 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
34240 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
34250 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
34260 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
34270 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
34280 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
34290 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 3c  te3_stmt.**.** <
342a0 62 3e 53 75 6d 6d 61 72 79 3a 3c 2f 62 3e 0a 2a  b>Summary:</b>.*
342b0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 74  * <blockquote><t
342c0 61 62 6c 65 20 62 6f 72 64 65 72 3d 30 20 63 65  able border=0 ce
342d0 6c 6c 70 61 64 64 69 6e 67 3d 30 20 63 65 6c 6c  llpadding=0 cell
342e0 73 70 61 63 69 6e 67 3d 30 3e 0a 2a 2a 20 3c 74  spacing=0>.** <t
342f0 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
34300 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 3c 2f 62 3e  _column_blob</b>
34310 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 42 4c  <td>&rarr;<td>BL
34320 4f 42 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  OB result.** <tr
34330 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
34340 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 3c 2f 62  column_double</b
34350 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 52  ><td>&rarr;<td>R
34360 45 41 4c 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  EAL result.** <t
34370 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
34380 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 3c 2f 62 3e 3c  _column_int</b><
34390 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 33 32 2d  td>&rarr;<td>32-
343a0 62 69 74 20 49 4e 54 45 47 45 52 20 72 65 73 75  bit INTEGER resu
343b0 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
343c0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
343d0 69 6e 74 36 34 3c 2f 62 3e 3c 74 64 3e 26 72 61  int64</b><td>&ra
343e0 72 72 3b 3c 74 64 3e 36 34 2d 62 69 74 20 49 4e  rr;<td>64-bit IN
343f0 54 45 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20  TEGER result.** 
34400 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
34410 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 3c 2f  e3_column_text</
34420 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e  b><td>&rarr;<td>
34430 55 54 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c  UTF-8 TEXT resul
34440 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
34450 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34460 65 78 74 31 36 3c 2f 62 3e 3c 74 64 3e 26 72 61  ext16</b><td>&ra
34470 72 72 3b 3c 74 64 3e 55 54 46 2d 31 36 20 54 45  rr;<td>UTF-16 TE
34480 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  XT result.** <tr
34490 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
344a0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 3c 2f 62 3e  column_value</b>
344b0 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 54 68  <td>&rarr;<td>Th
344c0 65 20 72 65 73 75 6c 74 20 61 73 20 61 6e 20 0a  e result as an .
344d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
344e0 65 7c 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  e|unprotected sq
344f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34500 65 63 74 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ect..** <tr><td>
34510 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73 70 3b  &nbsp;<td>&nbsp;
34520 3c 74 64 3e 26 6e 62 73 70 3b 0a 2a 2a 20 3c 74  <td>&nbsp;.** <t
34530 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
34540 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 3c 2f 62  _column_bytes</b
34550 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 53  ><td>&rarr;<td>S
34560 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 0a 2a 2a  ize of a BLOB.**
34570 20 6f 72 20 61 20 55 54 46 2d 38 20 54 45 58 54   or a UTF-8 TEXT
34580 20 72 65 73 75 6c 74 20 69 6e 20 62 79 74 65 73   result in bytes
34590 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73  .** <tr><td><b>s
345a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
345b0 74 65 73 31 36 26 6e 62 73 70 3b 26 6e 62 73 70  tes16&nbsp;&nbsp
345c0 3b 3c 2f 62 3e 0a 2a 2a 20 3c 74 64 3e 26 72 61  ;</b>.** <td>&ra
345d0 72 72 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c  rr;&nbsp;&nbsp;<
345e0 74 64 3e 53 69 7a 65 20 6f 66 20 55 54 46 2d 31  td>Size of UTF-1
345f0 36 0a 2a 2a 20 54 45 58 54 20 69 6e 20 62 79 74  6.** TEXT in byt
34600 65 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  es.** <tr><td><b
34610 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
34620 74 79 70 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  type</b><td>&rar
34630 72 3b 3c 74 64 3e 44 65 66 61 75 6c 74 0a 2a 2a  r;<td>Default.**
34640 20 64 61 74 61 74 79 70 65 20 6f 66 20 74 68 65   datatype of the
34650 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 2f 74 61 62   result.** </tab
34660 6c 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  le></blockquote>
34670 0a 2a 2a 0a 2a 2a 20 3c 62 3e 44 65 74 61 69 6c  .**.** <b>Detail
34680 73 3a 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68  s:</b>.**.** ^Th
34690 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
346a0 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
346b0 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
346c0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
346d0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
346e0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
346f0 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
34700 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
34710 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
34720 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
34730 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
34740 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
34750 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
34760 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
34770 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
34780 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
34790 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
347a0 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
347b0 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
347c0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
347d0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
347e0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
347f0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
34800 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
34810 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
34820 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
34830 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
34840 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
34850 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
34860 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
34870 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
34880 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
34890 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
348a0 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
348b0 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
348c0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
348d0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
348e0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
348f0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
34900 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
34910 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
34920 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
34930 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
34940 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
34950 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
34960 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
34970 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
34980 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
34990 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
349a0 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
349b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
349c0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
349d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
349e0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
349f0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
34a00 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
34a10 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
34a20 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
34a30 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
34a40 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
34a50 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
34a60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
34a70 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
34a80 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
34a90 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
34aa0 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
34ab0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
34ac0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
34ad0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
34ae0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
34af0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
34b00 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
34b10 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
34b20 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
34b30 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
34b40 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
34b50 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
34b60 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
34b70 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ned..**.** The f
34b80 69 72 73 74 20 73 69 78 20 69 6e 74 65 72 66 61  irst six interfa
34b90 63 65 73 20 28 5f 62 6c 6f 62 2c 20 5f 64 6f 75  ces (_blob, _dou
34ba0 62 6c 65 2c 20 5f 69 6e 74 2c 20 5f 69 6e 74 36  ble, _int, _int6
34bb0 34 2c 20 5f 74 65 78 74 2c 20 61 6e 64 20 5f 74  4, _text, and _t
34bc0 65 78 74 31 36 29 0a 2a 2a 20 65 61 63 68 20 72  ext16).** each r
34bd0 65 74 75 72 6e 20 74 68 65 20 76 61 6c 75 65 20  eturn the value 
34be0 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
34bf0 6d 6e 20 69 6e 20 61 20 73 70 65 63 69 66 69 63  mn in a specific
34c00 20 64 61 74 61 20 66 6f 72 6d 61 74 2e 20 20 49   data format.  I
34c10 66 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 20  f.** the result 
34c20 63 6f 6c 75 6d 6e 20 69 73 20 6e 6f 74 20 69 6e  column is not in
34c30 69 74 69 61 6c 6c 79 20 69 6e 20 74 68 65 20 72  itially in the r
34c40 65 71 75 65 73 74 65 64 20 66 6f 72 6d 61 74 20  equested format 
34c50 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
34c60 20 69 66 20 74 68 65 20 71 75 65 72 79 20 72 65   if the query re
34c70 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
34c80 20 62 75 74 20 74 68 65 20 73 71 6c 69 74 65 33   but the sqlite3
34c90 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
34ca0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 75  nterface.** is u
34cb0 73 65 64 20 74 6f 20 65 78 74 72 61 63 74 20 74  sed to extract t
34cc0 68 65 20 76 61 6c 75 65 29 20 74 68 65 6e 20 61  he value) then a
34cd0 6e 20 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65  n automatic type
34ce0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
34cf0 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a 20  erformed..**.** 
34d00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
34d10 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
34d20 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
34d30 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
34d40 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
34d50 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
34d60 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
34d70 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
34d80 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
34d90 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
34da0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
34db0 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
34dc0 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
34dd0 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
34de0 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
34df0 54 45 5f 4e 55 4c 4c 5d 2e 0a 2a 2a 20 54 68 65  TE_NULL]..** The
34e00 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
34e10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34e20 74 79 70 65 28 29 20 63 61 6e 20 62 65 20 75 73  type() can be us
34e30 65 64 20 74 6f 20 64 65 63 69 64 65 20 77 68 69  ed to decide whi
34e40 63 68 0a 2a 2a 20 6f 66 20 74 68 65 20 66 69 72  ch.** of the fir
34e50 73 74 20 73 69 78 20 69 6e 74 65 72 66 61 63 65  st six interface
34e60 20 73 68 6f 75 6c 64 20 62 65 20 75 73 65 64 20   should be used 
34e70 74 6f 20 65 78 74 72 61 63 74 20 74 68 65 20 63  to extract the c
34e80 6f 6c 75 6d 6e 20 76 61 6c 75 65 2e 0a 2a 2a 20  olumn value..** 
34e90 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
34ea0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
34eb0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
34ec0 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
34ed0 66 20 6e 6f 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  f no.** automati
34ee0 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  c type conversio
34ef0 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
34f00 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 20 69   for the value i
34f10 6e 20 71 75 65 73 74 69 6f 6e 2e 20 20 0a 2a 2a  n question.  .**
34f20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
34f30 6e 76 65 72 73 69 6f 6e 2c 20 74 68 65 20 72 65  nversion, the re
34f40 73 75 6c 74 20 6f 66 20 63 61 6c 6c 69 6e 67 20  sult of calling 
34f50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34f60 79 70 65 28 29 0a 2a 2a 20 69 73 20 75 6e 64 65  ype().** is unde
34f70 66 69 6e 65 64 2c 20 74 68 6f 75 67 68 20 68 61  fined, though ha
34f80 72 6d 6c 65 73 73 2e 20 20 46 75 74 75 72 65 0a  rmless.  Future.
34f90 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
34fa0 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
34fb0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
34fc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34fd0 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
34fe0 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
34ff0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rsion..**.** If 
35000 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
35010 42 4c 4f 42 20 6f 72 20 61 20 54 45 58 54 20 73  BLOB or a TEXT s
35020 74 72 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  tring, then the 
35030 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35040 79 74 65 73 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  ytes().** or sql
35050 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35060 73 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 73  s16() interfaces
35070 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
35080 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73 69  determine the si
35090 7a 65 0a 2a 2a 20 6f 66 20 74 68 61 74 20 42 4c  ze.** of that BL
350a0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
350b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
350c0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
350d0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
350e0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
350f0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
35100 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
35110 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
35120 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
35130 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
35140 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
35150 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
35160 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
35170 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
35180 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
35190 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
351a0 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
351b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
351c0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
351d0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
351e0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
351f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35200 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
35210 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
35220 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
35230 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
35240 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
35250 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
35260 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
35270 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
35280 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
35290 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
352a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
352b0 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
352c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
352d0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
352e0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
352f0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
35300 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
35310 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
35320 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
35330 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
35340 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
35350 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
35360 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
35370 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
35380 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35390 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
353a0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
353b0 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
353c0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
353d0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
353e0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
353f0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
35400 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
35410 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
35420 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
35430 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
35440 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
35450 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
35460 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
35470 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
35480 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
35490 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
354a0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
354b0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
354c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
354d0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
354e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
354f0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
35500 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35510 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
35520 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35530 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
35540 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
35550 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
35560 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
35570 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
35580 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
35590 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
355a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
355b0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
355c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
355d0 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
355e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
355f0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
35600 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
35610 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
35620 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
35630 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
35640 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35650 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
35660 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
35670 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
35680 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
35690 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
356a0 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
356b0 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
356c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
356d0 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
356e0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
356f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
35700 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67  **.** <b>Warning
35710 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63  :</b> ^The objec
35720 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
35730 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
35740 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
35750 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
35760 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
35770 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74  ct.  In a multit
35780 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d  hreaded environm
35790 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f  ent,.** an unpro
357a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
357b0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
357c0 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61 66  only be used saf
357d0 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  ely with.** [sql
357e0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
357f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
35800 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
35810 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
35820 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
35830 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
35840 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
35850 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
35860 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
35870 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
35880 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
35890 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
358a0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
358b0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
358c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
358d0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
358e0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
358f0 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
35900 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
35910 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 74 68 65 20  ..** Hence, the 
35920 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
35930 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
35940 0a 2a 2a 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20  .** is normally 
35950 6f 6e 6c 79 20 75 73 65 66 75 6c 20 77 69 74 68  only useful with
35960 69 6e 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  in the implement
35970 61 74 69 6f 6e 20 6f 66 20 0a 2a 2a 20 5b 61 70  ation of .** [ap
35980 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35990 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
359a0 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
359b0 6c 65 73 5d 2c 20 6e 6f 74 20 77 69 74 68 69 6e  les], not within
359c0 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 61 70  .** top-level ap
359d0 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 2e 0a  plication code..
359e0 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 65 73 65 20  **.** The these 
359f0 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 61 74 74  routines may att
35a00 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
35a10 74 68 65 20 64 61 74 61 74 79 70 65 20 6f 66 20  the datatype of 
35a20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  the result..** ^
35a30 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
35a40 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
35a50 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
35a60 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
35a70 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
35a80 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
35a90 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
35aa0 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
35ab0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
35ac0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
35ad0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
35ae0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
35af0 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
35b00 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
35b10 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
35b20 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
35b30 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
35b40 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
35b50 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
35b60 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
35b70 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
35b80 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
35b90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
35ba0 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
35bb0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
35bc0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
35bd0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
35be0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
35bf0 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
35c00 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
35c10 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
35c20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
35c30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
35c40 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
35c50 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
35c60 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
35c70 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
35c80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
35c90 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
35ca0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
35cb0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
35cc0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
35cd0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
35ce0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
35cf0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
35d00 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
35d10 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
35d20 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
35d30 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
35d40 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
35d50 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
35d60 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
35d70 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
35d80 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
35d90 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
35da0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
35db0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
35dc0 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
35dd0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
35de0 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
35df0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
35e00 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
35e10 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
35e20 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
35e30 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
35e40 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
35e50 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
35e60 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
35e70 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
35e80 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
35e90 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
35ea0 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
35eb0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
35ec0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
35ed0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
35ee0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
35ef0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
35f00 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
35f10 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
35f20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
35f30 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
35f40 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
35f50 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
35f60 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
35f70 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
35f80 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e  quote>)^.**.** N
35f90 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
35fa0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
35fb0 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
35fc0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
35fd0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
35fe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
35ff0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
36000 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
36010 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
36020 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
36030 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
36040 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
36050 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
36060 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
36070 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
36080 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
36090 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
360a0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
360b0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
360c0 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
360d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
360e0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
360f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
36100 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
36110 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
36120 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
36130 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
36140 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
36150 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
36160 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
36170 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
36180 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
36190 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
361a0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
361b0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
361c0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
361d0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
361e0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
361f0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
36200 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
36210 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
36220 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
36230 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36240 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
36250 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
36260 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
36270 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
36280 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
36290 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
362a0 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
362b0 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
362c0 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
362d0 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
362e0 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
362f0 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
36300 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
36310 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
36320 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
36330 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
36340 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
36350 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
36360 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
36370 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
36380 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
36390 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
363a0 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
363b0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
363c0 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
363d0 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
363e0 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
363f0 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
36400 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
36410 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
36420 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
36430 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70  .** The safest p
36440 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
36450 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
36460 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
36470 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
36480 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
36490 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
364a0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
364b0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
364c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
364d0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
364e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
364f0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
36500 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36510 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
36520 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
36530 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
36540 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
36550 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
36560 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
36570 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
36580 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
36590 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
365a0 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
365b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
365c0 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
365d0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
365e0 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
365f0 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
36600 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
36610 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
36620 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36630 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
36640 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36650 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
36660 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
36670 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
36680 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
36690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
366a0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
366b0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
366c0 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
366d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
366e0 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
366f0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
36700 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36710 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
36720 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
36730 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
36740 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
36750 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
36760 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
36770 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
36780 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
36790 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
367a0 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
367b0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
367c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
367d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
367e0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
367f0 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
36800 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
36810 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
36820 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
36830 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
36840 20 20 44 6f 20 6e 6f 74 20 70 61 73 73 20 74 68    Do not pass th
36850 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
36860 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
36870 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
36880 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
36890 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
368a0 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
368b0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
368c0 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
368d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
368e0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
368f0 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
36900 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
36910 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
36920 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
36930 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
36940 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
36950 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
36960 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
36970 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
36980 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
36990 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
369a0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
369b0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
369c0 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
369d0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
369e0 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20  EM].)^.*/.const 
369f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
36a00 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
36a10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
36a20 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
36a30 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
36a40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
36a50 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
36a60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
36a70 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
36a80 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
36a90 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
36aa0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
36ab0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
36ac0 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
36ad0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
36ae0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
36af0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
36b00 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
36b10 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
36b20 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
36b30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
36b40 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
36b50 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
36b60 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
36b70 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36b80 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
36b90 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
36ba0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
36bb0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
36bc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
36bd0 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
36be0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
36bf0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
36c00 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
36c10 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
36c20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36c30 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
36c40 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
36c50 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54  ject.** DESTRUCT
36c60 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
36c70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36c80 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
36c90 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
36ca0 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
36cb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36cc0 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
36cd0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
36ce0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
36cf0 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
36d00 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
36d10 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
36d20 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
36d30 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
36d40 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
36d50 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
36d60 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
36d70 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
36d80 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
36d90 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
36da0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
36db0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
36dc0 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
36dd0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
36de0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
36df0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
36e00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36e10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
36e20 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
36e30 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
36e40 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
36e50 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
36e60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36e70 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
36e80 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
36e90 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
36ea0 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
36eb0 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
36ec0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
36ed0 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
36ee0 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
36ef0 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
36f00 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
36f10 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
36f20 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
36f30 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
36f40 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
36f50 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
36f60 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
36f70 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
36f80 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
36f90 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
36fa0 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
36fb0 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
36fc0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
36fd0 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
36fe0 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
36ff0 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
37000 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
37010 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
37020 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
37030 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
37040 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
37050 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
37060 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
37070 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
37080 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
37090 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
370a0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
370b0 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
370c0 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
370d0 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
370e0 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
370f0 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  uption..*/.int s
37100 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
37110 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
37120 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
37130 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
37140 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
37150 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48  t Object.** METH
37160 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
37170 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
37180 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
37190 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
371a0 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
371b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
371c0 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
371d0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
371e0 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
371f0 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
37200 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
37210 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
37220 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
37230 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
37240 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
37250 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
37260 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
37270 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
37280 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
37290 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
372a0 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
372b0 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
372c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
372d0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
372e0 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
372f0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
37300 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
37310 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
37320 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
37330 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
37340 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
37350 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
37360 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
37370 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
37380 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
37390 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
373a0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
373b0 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
373c0 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
373d0 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
373e0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
373f0 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
37400 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
37410 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
37420 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
37430 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
37440 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
37450 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
37460 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
37470 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
37480 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
37490 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
374a0 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
374b0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
374c0 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
374d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
374e0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
374f0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
37500 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
37510 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
37520 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
37530 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
37540 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
37550 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
37560 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
37570 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
37580 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
37590 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
375a0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
375b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
375c0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
375d0 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
375e0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
375f0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
37600 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
37610 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
37620 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
37630 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
37640 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
37650 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
37660 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
37670 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
37680 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
37690 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
376a0 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
376b0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
376c0 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
376d0 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
376e0 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
376f0 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
37700 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
37710 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
37720 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
37730 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
37740 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
37750 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
37760 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
37770 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
37780 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
37790 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
377a0 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
377b0 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
377c0 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
377d0 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
377e0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
377f0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
37800 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
37810 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
37820 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
37830 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
37840 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
37850 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
37860 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
37870 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
37880 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
37890 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
378a0 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
378b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
378c0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
378d0 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
378e0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
378f0 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
37900 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
37910 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
37920 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
37930 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
37940 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
37950 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
37960 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
37970 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
37980 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
37990 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
379a0 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
379b0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
379c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
379d0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
379e0 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
379f0 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
37a00 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
37a10 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
37a20 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
37a30 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
37a40 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
37a50 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
37a60 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
37a70 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
37a80 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
37a90 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
37aa0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
37ab0 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
37ac0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
37ad0 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
37ae0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
37af0 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
37b00 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
37b10 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
37b20 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
37b30 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
37b40 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
37b50 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
37b60 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
37b70 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
37b80 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
37b90 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
37ba0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
37bb0 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
37bc0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
37bd0 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
37be0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
37bf0 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
37c00 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
37c10 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
37c20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
37c30 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
37c40 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
37c50 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
37c60 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
37c70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
37c80 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
37c90 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68   parameters.  Th
37ca0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
37cb0 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61  ould set this pa
37cc0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53  rameter to.** [S
37cd0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69  QLITE_UTF16LE] i
37ce0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
37cf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
37d00 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74  vokes .** [sqlit
37d10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
37d20 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
37d30 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
37d40 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20  16BE] if the.** 
37d50 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
37d60 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f  nvokes [sqlite3_
37d70 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
37d80 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
37d90 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  r.** [SQLITE_UTF
37da0 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  16] if [sqlite3_
37db0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
37dc0 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c  is used, or [SQL
37dd0 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68  ITE_UTF8].** oth
37de0 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61  erwise.  ^The sa
37df0 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
37e00 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
37e10 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
37e20 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72   using.** differ
37e30 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65  ent preferred te
37e40 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69  xt encodings, wi
37e50 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70  th different imp
37e60 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
37e70 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e  .** each encodin
37e80 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  g..** ^When mult
37e90 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
37ea0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
37eb0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
37ec0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
37ed0 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
37ee0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
37ef0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
37f00 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
37f10 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ersion..**.** ^T
37f20 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
37f30 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c  ter may optional
37f40 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20  ly be ORed with 
37f50 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
37f60 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67  ISTIC].** to sig
37f70 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e  nal that the fun
37f80 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79  ction will alway
37f90 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
37fa0 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a  e result given.*
37fb0 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  * the same input
37fc0 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c  s within a singl
37fd0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
37fe0 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74    Most SQL funct
37ff0 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65  ions are.** dete
38000 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
38010 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d  built-in [random
38020 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
38030 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
38040 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  f a.** function 
38050 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65  that is not dete
38060 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
38070 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61  SQLite query pla
38080 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a  nner is able to.
38090 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74  ** perform addit
380a0 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69  ional optimizati
380b0 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69  ons on determini
380c0 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20  stic functions, 
380d0 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65  so use.** of the
380e0 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49   [SQLITE_DETERMI
380f0 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20  NISTIC] flag is 
38100 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72  recommended wher
38110 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a  e possible..**.*
38120 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
38130 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
38140 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
38150 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
38160 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
38170 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
38180 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
38190 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
381a0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
381b0 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
381c0 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
381d0 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
381e0 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
381f0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
38200 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
38210 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
38220 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
38230 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
38240 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
38250 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
38260 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
38270 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
38280 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
38290 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
382a0 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
382b0 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
382c0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
382d0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
382e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
382f0 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
38300 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
38310 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
38320 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
38330 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
38340 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
38350 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
38360 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
38370 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
38380 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
38390 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
383a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
383b0 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
383c0 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
383d0 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
383e0 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
383f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
38400 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
38410 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
38420 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
38430 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
38440 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
38450 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
38460 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
38470 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
38480 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
38490 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
384a0 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
384b0 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
384c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
384d0 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
384e0 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
384f0 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
38500 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
38510 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
38520 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
38530 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
38540 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
38550 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
38560 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
38570 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
38580 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
38590 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
385a0 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
385b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
385c0 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
385d0 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
385e0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
385f0 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
38600 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
38610 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
38620 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
38630 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
38640 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
38650 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
38660 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
38670 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
38680 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
38690 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
386a0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
386b0 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
386c0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
386d0 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
386e0 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
386f0 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
38700 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
38710 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
38720 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
38730 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
38740 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
38750 6