/ Hex Artifact Content
Login

Artifact 82ffe3190542d8f9f618ef94e3b86b1761b4517ba6d3df74ab24c17c58633594:


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 0a 2a 2a 0a  source tree..**.
10c0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
10d0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
10e0: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
10f0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
1100: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
1110: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
1120: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
1130: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
1140: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1160: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
1170: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1180: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1190: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
11a0: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
11b0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
11c0: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
11d0: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
11e0: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
11f0: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1200: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1210: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
1220: 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73  ersion sqlite3_s
1230: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
1240: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
1250: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
1260: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
1270: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1280: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1290: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
12a0: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
12b0: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
12c0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
12d0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
12e0: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
12f0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1300: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1310: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
1320: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
1330: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
1340: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
1350: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
1360: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
1370: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1380: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1390: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
13a0: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
13b0: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
13c0: 74 68 75 73 20 65 6e 73 75 72 65 20 74 68 61 74  thus ensure that
13d0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
13e0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
13f0: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1400: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1410: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
1420: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1430: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1450: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
1460: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
1470: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1480: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1490: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
14a0: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
14b0: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
14c0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
14d0: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
14e0: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
14f0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1500: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1510: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1520: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1530: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
1540: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
1550: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
1560: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
1570: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1580: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1590: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
15a0: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
15b0: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
15c0: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
15d0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
15e0: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
15f0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1600: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1610: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
1620: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
1630: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
1640: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
1650: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
1660: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
1670: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1680: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1690: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
16a0: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
16b0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
16c0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
16d0: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
16e0: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
16f0: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1700: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1710: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
1720: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
1730: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
1740: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
1750: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1760: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
1770: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1780: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1790: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
17a0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
17b0: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
17c0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
17d0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
17e0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
17f0: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1800: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1810: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
1820: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1830: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1840: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1850: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
1860: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
1870: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1880: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1890: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
18a0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
18b0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
18c0: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
18d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
18e0: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
18f0: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1900: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1910: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1920: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1930: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1940: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1950: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1960: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1970: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1980: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1990: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
19a0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
19b0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
19c0: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
19d0: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
19e0: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
19f0: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1a00: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1a10: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1a20: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1a30: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1a40: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1a60: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1a70: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1a80: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1a90: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
1aa0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
1ab0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
1ac0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1ad0: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
1ae0: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
1af0: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1b00: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1b10: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1b20: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1b30: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1b40: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1b50: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1b60: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1b70: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1b80: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1b90: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1ba0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1bb0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1bc0: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1bd0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1be0: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1bf0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1c00: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1c10: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1c20: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1c30: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1c40: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1c50: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1c60: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1c70: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1c80: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1c90: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1ca0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1cb0: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1cc0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1cd0: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1ce0: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1cf0: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1d00: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1d10: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1d20: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1d30: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1d40: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1d50: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
1d60: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
1d70: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
1d80: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d90: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
1da0: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
1db0: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
1dc0: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
1dd0: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
1de0: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
1df0: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
1e00: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
1e10: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1e20: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
1e30: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
1e40: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
1e50: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
1e60: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
1e70: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1e80: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
1e90: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
1ea0: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
1eb0: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
1ec0: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
1ed0: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
1ee0: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
1ef0: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
1f00: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
1f10: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
1f20: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
1f30: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
1f40: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
1f50: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
1f60: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
1f70: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
1f80: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
1f90: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
1fa0: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
1fb0: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
1fc0: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
1fd0: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
1fe0: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
1ff0: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
2000: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2010: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2020: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
2030: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
2040: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
2050: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
2060: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
2070: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
2080: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
2090: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
20a0: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
20b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
20c0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
20d0: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
20e0: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
20f0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
2100: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
2110: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
2120: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
2130: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2140: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
2150: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
2160: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
2170: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
2180: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
2190: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
21a0: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
21b0: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
21c0: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
21d0: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
21e0: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
21f0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
2200: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
2210: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
2220: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
2230: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
2240: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2260: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2270: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2280: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
2290: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
22a0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
22b0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
22c0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
22d0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
22e0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
22f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2300: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2310: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2320: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2330: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2340: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2350: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2360: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2370: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2380: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
2390: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
23a0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
23b0: 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
23c0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
23d0: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
23e0: 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
23f0: 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64   Connection Hand
2400: 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  le.** KEYWORDS: 
2410: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2420: 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20  tion} {database 
2430: 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  connections}.**.
2440: 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c  ** Each open SQL
2450: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
2460: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
2470: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
2480: 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68  nstance of.** th
2490: 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74 75  e opaque structu
24a0: 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65  re named "sqlite
24b0: 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66 75  3".  It is usefu
24c0: 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e  l to think of an
24d0: 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e   sqlite3.** poin
24e0: 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74  ter as an object
24f0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
2500: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2510: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64  3_open16()], and
2520: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2530: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
2540: 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74  es are its const
2550: 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71  ructors, and [sq
2560: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a  lite3_close()].*
2570: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2580: 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69  lose_v2()] are i
2590: 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20  ts destructors. 
25a0: 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20   There are many 
25b0: 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61  other.** interfa
25c0: 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20  ces (such as.** 
25d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
25e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
25f0: 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2600: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2610: 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
2620: 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74  t()] to name but
2630: 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72 65   three) that are
2640: 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a   methods on an.*
2650: 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74  * sqlite3 object
2660: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2670: 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69  uct sqlite3 sqli
2680: 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  te3;../*.** CAPI
2690: 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74  3REF: 64-Bit Int
26a0: 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45  eger Types.** KE
26b0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69  YWORDS: sqlite_i
26c0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
26d0: 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  64.**.** Because
26e0: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f   there is no cro
26f0: 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20  ss-platform way 
2700: 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62 69  to specify 64-bi
2710: 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a  t integer types.
2720: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64  ** SQLite includ
2730: 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72 20  es typedefs for 
2740: 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e  64-bit signed an
2750: 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  d unsigned integ
2760: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ers..**.** The s
2770: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
2780: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2790: 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  are the preferre
27a0: 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f  d type definitio
27b0: 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ns..** The sqlit
27c0: 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  e_int64 and sqli
27d0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
27e0: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f  are supported fo
27f0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
2800: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
2810: 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
2820: 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20  lite3_int64 and 
2830: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70  sqlite_int64 typ
2840: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2850: 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62  eger values.** b
2860: 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30  etween -92233720
2870: 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64 20  36854775808 and 
2880: 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  +922337203685477
2890: 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20  5807 inclusive. 
28a0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
28b0: 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  _uint64 and sqli
28c0: 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20  te_uint64 types 
28d0: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
28e0: 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74  r values .** bet
28f0: 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34  ween 0 and +1844
2900: 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31 35  6744073709551615
2910: 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23   inclusive..*/.#
2920: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54  ifdef SQLITE_INT
2930: 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65  64_TYPE.  typede
2940: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2950: 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  YPE sqlite_int64
2960: 3b 0a 23 20 69 66 64 65 66 20 53 51 4c 49 54 45  ;.# ifdef SQLITE
2970: 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 20  _UINT64_TYPE.   
2980: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2990: 55 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  UINT64_TYPE sqli
29a0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73  te_uint64;.# els
29b0: 65 20 20 0a 20 20 20 20 74 79 70 65 64 65 66 20  e  .    typedef 
29c0: 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f  unsigned SQLITE_
29d0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
29e0: 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69  e_uint64;.# endi
29f0: 66 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  f.#elif defined(
2a00: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2a10: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2a20: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2a30: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2a40: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2a50: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2a60: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2a70: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
2a80: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2a90: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2aa0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
2ab0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2ac0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
2ad0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2ae0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2af0: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2b00: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2b10: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2b20: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2b30: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2b40: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2b50: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2b60: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2b70: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
2b80: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
2b90: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
2ba0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
2bb0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
2bc0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
2bd0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2be0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2bf0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2c00: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
2c10: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
2c20: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2c30: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2c40: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2c50: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2c60: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2c70: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2c80: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2c90: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ca0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2cb0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2cc0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2cd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2ce0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2cf0: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2d00: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2d10: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2d20: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2d30: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2d40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d50: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2d60: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2d70: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2d80: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2d90: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2da0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2db0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2dc0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2dd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2de0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2df0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2e00: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2e10: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2e20: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2e30: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2e40: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2e50: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2e60: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2e70: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2e80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e90: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2ea0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2eb0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2ec0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2ed0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2ee0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2ef0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2f00: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2f10: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2f20: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2f30: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2f40: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2f50: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2f60: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2f70: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2f80: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2f90: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2fa0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2fb0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2fc0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2fd0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2fe0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2ff0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
3000: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3010: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
3020: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3030: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
3040: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
3050: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
3060: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
3070: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
3080: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
3090: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
30a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
30b0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
30c0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
30d0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
30e0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
30f0: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
3100: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
3110: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
3120: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
3130: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3140: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
3150: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
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 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3180: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3190: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
31a0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
31b0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
31c0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
31d0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
31e0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
31f0: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3200: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3210: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3220: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3230: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3240: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3250: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3260: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3270: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3280: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
3290: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
32a0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
32b0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
32c0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
32d0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
32e0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
32f0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3300: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3310: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3320: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3330: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3340: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3350: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3360: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3370: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3380: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
3390: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
33a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
33b0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
33c0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
33d0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
33e0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
33f0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3400: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3410: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3420: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3430: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3440: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3450: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
3460: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
3470: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
3480: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
3490: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
34a0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
34b0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
34c0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
34d0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
34e0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
34f0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3500: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3510: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3520: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3530: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3540: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3550: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
3560: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
3570: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
3580: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
3590: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
35a0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
35b0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
35c0: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
35d0: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
35e0: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
35f0: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
3600: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
3610: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
3620: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
3630: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
3640: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
3650: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
3660: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
3670: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
3680: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
3690: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
36a0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
36b0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
36c0: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
36d0: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
36e0: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
36f0: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
3700: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
3710: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
3720: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3730: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
3740: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
3750: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
3760: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3770: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
3780: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
3790: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
37a0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
37b0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
37c0: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
37d0: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
37e0: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
37f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
3800: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3810: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
3820: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
3830: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
3840: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
3850: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
3860: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
3870: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3880: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
3890: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
38a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
38b0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
38c0: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
38d0: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
38e0: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
38f0: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
3900: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
3910: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
3920: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
3930: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3940: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
3950: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
3960: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
3970: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
3980: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
3990: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
39a0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
39b0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
39c0: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
39d0: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
39e0: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
39f0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
3a00: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
3a10: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
3a20: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
3a30: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
3a40: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
3a50: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
3a60: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
3a70: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
3a80: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
3a90: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
3aa0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
3ab0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
3ac0: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3ad0: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73  arameter of.** s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3af0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3b00: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3b10: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3b20: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3b30: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3b40: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3b50: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3b60: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3b70: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3b80: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3b90: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3ba0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3bb0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3bc0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3bd0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3be0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3bf0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3c00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3c10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3c20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3c30: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3c40: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3c50: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3c60: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3c70: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3c80: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3c90: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3ca0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3cb0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3cc0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3cd0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3ce0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3cf0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3d00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3d10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3d20: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3d30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3d40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3d50: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3d60: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3d70: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3d80: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3d90: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3da0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3db0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3dc0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3dd0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3de0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3df0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3e00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3e10: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3e20: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3e30: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3e40: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3e50: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3e60: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3e70: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3e80: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3e90: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3ea0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3eb0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3ec0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3ed0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3ee0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3ef0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3f00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3f10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3f20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3f30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3f40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3f50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3f60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3f70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3f80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3f90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3fa0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3fb0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3fc0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3fd0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3fe0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3ff0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
4000: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4010: 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  t ensure that th
4020: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
4030: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
4040: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
4050: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
4060: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4070: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
4080: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
4090: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
40a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
40b0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
40c0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
40d0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
40e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
40f0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
4100: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
4110: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
4120: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
4130: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
4140: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
4150: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
4160: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
4170: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
4180: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
4190: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
41a0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
41b0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
41c0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
41d0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41f0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4200: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4210: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4240: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4250: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4260: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4270: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4280: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4290: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
42d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
42e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
42f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4310: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4320: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4330: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4340: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4350: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4360: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4370: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4380: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4390: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
43a0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
43b0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
43c0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
43d0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
43e0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
43f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4400: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4410: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4420: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4430: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4440: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4450: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4460: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4470: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4480: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4490: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
44a0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
44b0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
44c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
44d0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
44e0: 2f 2a 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72  /* Generic error
44f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4500: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4510: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4520: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4530: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4540: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4550: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4560: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4570: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4580: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
4590: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
45a0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
45b0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45d0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
45e0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
45f0: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4600: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4610: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4620: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4630: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4640: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4650: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4660: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4670: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4690: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
46a0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
46b0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
46c0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
46d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
46e0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
46f0: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4700: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4710: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4730: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4740: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4750: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4760: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4770: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4780: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
4790: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
47a0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
47b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
47c0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
47d0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
47e0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
47f0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4800: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4810: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4820: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4830: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4840: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4850: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4860: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4870: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4880: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
4890: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
48a0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
48b0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
48c0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
48d0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
48f0: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4900: 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a 23 64  * Not used */.#d
4910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4920: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4930: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4940: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4960: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4970: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
4980: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
4990: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
49a0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
49b0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
49c0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
49d0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
49e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
49f0: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a00: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4a10: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4a20: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4a30: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4a40: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4a50: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4a60: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4a70: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4a80: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4a90: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4aa0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4ab0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4ac0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4ad0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4ae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4af0: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b00: 2f 2a 20 4e 6f 74 20 75 73 65 64 20 2a 2f 0a 23  /* Not used */.#
4b10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4b20: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4b30: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4b40: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4b50: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4b70: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
4b80: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
4b90: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
4ba0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4bb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4bc0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4bd0: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4be0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4bf0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4c00: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4c10: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4c20: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4c30: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4c40: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4c50: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4c60: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4c70: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4c80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4c90: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4ca0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4cb0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4cc0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4cd0: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4ce0: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4cf0: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4d00: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4d10: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4d20: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4d30: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4d40: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4d50: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4d60: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4d70: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4d80: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4d90: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4da0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4db0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4dc0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4dd0: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4de0: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4df0: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4e00: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4e10: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4e20: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4e30: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4e40: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4e50: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4e60: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4e70: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4e80: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4e90: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 74  rsion 3.3.8 [dat
4ea0: 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e  eof:3.3.8].** an
4eb0: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4ec0: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4ed0: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
4ee0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
4ef0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
4f00: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
4f10: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
4f20: 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20  These [extended 
4f30: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72  result codes] ar
4f40: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4f50: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4f60: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4f70: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4f80: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4f90: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4fa0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20  t_codes()] API. 
4fb0: 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65   Or, the extende
4fc0: 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68  d code for.** th
4fd0: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72  e most recent er
4fe0: 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69  ror can be obtai
4ff0: 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
5000: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
5010: 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64  rrcode()]..*/.#d
5020: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5030: 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  RR_READ         
5040: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5050: 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  RR | (1<<8)).#de
5060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5070: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20  R_SHORT_READ    
5080: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5090: 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  R | (2<<8)).#def
50a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50b0: 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  _WRITE          
50c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50d0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
50f0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  FSYNC           
5100: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5110: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5120: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
5130: 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  IR_FSYNC        
5140: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5150: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5160: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52   SQLITE_IOERR_TR
5170: 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20  UNCATE          
5180: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5190: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
51a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54  SQLITE_IOERR_FST
51b0: 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28  AT             (
51c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
51d0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
51e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f  QLITE_IOERR_UNLO
51f0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5200: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38  QLITE_IOERR | (8
5210: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5220: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43  LITE_IOERR_RDLOC
5230: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
5240: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c  LITE_IOERR | (9<
5250: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5260: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
5270: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5280: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c  ITE_IOERR | (10<
5290: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52a0: 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
52b0: 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  D           (SQL
52c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c  ITE_IOERR | (11<
52d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
52e0: 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20  ITE_IOERR_NOMEM 
52f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5300: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c  ITE_IOERR | (12<
5310: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5320: 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53  ITE_IOERR_ACCESS
5330: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5340: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c  ITE_IOERR | (13<
5350: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5360: 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52  ITE_IOERR_CHECKR
5370: 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c  ESERVEDLOCK (SQL
5380: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c  ITE_IOERR | (14<
5390: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53a0: 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20  ITE_IOERR_LOCK  
53b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
53c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c  ITE_IOERR | (15<
53d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
53e0: 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20  ITE_IOERR_CLOSE 
53f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5400: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c  ITE_IOERR | (16<
5410: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5420: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c  ITE_IOERR_DIR_CL
5430: 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c  OSE         (SQL
5440: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c  ITE_IOERR | (17<
5450: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5460: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45  ITE_IOERR_SHMOPE
5470: 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  N           (SQL
5480: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c  ITE_IOERR | (18<
5490: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54a0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a  ITE_IOERR_SHMSIZ
54b0: 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  E           (SQL
54c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c  ITE_IOERR | (19<
54d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
54e0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43  ITE_IOERR_SHMLOC
54f0: 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  K           (SQL
5500: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c  ITE_IOERR | (20<
5510: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5520: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50  ITE_IOERR_SHMMAP
5530: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5540: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c  ITE_IOERR | (21<
5550: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5560: 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20  ITE_IOERR_SEEK  
5570: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5580: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c  ITE_IOERR | (22<
5590: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55a0: 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45  ITE_IOERR_DELETE
55b0: 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c  _NOENT      (SQL
55c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c  ITE_IOERR | (23<
55d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55e0: 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20  ITE_IOERR_MMAP  
55f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5600: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c  ITE_IOERR | (24<
5610: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5620: 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d  ITE_IOERR_GETTEM
5630: 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  PPATH       (SQL
5640: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c  ITE_IOERR | (25<
5650: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5660: 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41  ITE_IOERR_CONVPA
5670: 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TH          (SQL
5680: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c  ITE_IOERR | (26<
5690: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56a0: 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20  ITE_IOERR_VNODE 
56b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
56c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c  ITE_IOERR | (27<
56d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56e0: 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20  ITE_IOERR_AUTH  
56f0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5700: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c  ITE_IOERR | (28<
5710: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5720: 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45  ITE_LOCKED_SHARE
5730: 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c  DCACHE      (SQL
5740: 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31  ITE_LOCKED |  (1
5750: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5760: 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45  LITE_BUSY_RECOVE
5770: 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51  RY           (SQ
5780: 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28  LITE_BUSY   |  (
5790: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
57a0: 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53  QLITE_BUSY_SNAPS
57b0: 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 53  HOT           (S
57c0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
57d0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
57e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
57f0: 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 28  NOTEMPDIR      (
5800: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5810: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5820: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5830: 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 20  N_ISDIR         
5840: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5850: 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  N | (2<<8)).#def
5860: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5870: 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20  PEN_FULLPATH    
5880: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5890: 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  PEN | (3<<8)).#d
58a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
58b0: 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20  TOPEN_CONVPATH  
58c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
58d0: 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a  TOPEN | (4<<8)).
58e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
58f0: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5900: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5910: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5930: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
5940: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
5950: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
5960: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5970: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
5980: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
5990: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
59a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
59b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c  ITE_READONLY_ROL
59c0: 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c  LBACK       (SQL
59d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
59e0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
59f0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44  QLITE_READONLY_D
5a00: 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 53  BMOVED        (S
5a10: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5a20: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5a30: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5a40: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5a50: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5a60: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5a70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a80: 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28  T_CHECK        (
5a90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5aa0: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
5ab0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ac0: 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b  RAINT_COMMITHOOK
5ad0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ae0: 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a  RAINT | (2<<8)).
5af0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b00: 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47  ONSTRAINT_FOREIG
5b10: 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  NKEY   (SQLITE_C
5b20: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c  ONSTRAINT | (3<<
5b30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55  TE_CONSTRAINT_FU
5b50: 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49  NCTION     (SQLI
5b60: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b70: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
5b80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b90: 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28  T_NOTNULL      (
5ba0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5bb0: 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  T | (5<<8)).#def
5bc0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5bd0: 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59  RAINT_PRIMARYKEY
5be0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5bf0: 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a  RAINT | (6<<8)).
5c00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c10: 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45  ONSTRAINT_TRIGGE
5c20: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5c30: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c  ONSTRAINT | (7<<
5c40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c50: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e  TE_CONSTRAINT_UN
5c60: 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49  IQUE       (SQLI
5c70: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c80: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
5c90: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5ca0: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28  T_VTAB         (
5cb0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5cc0: 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  T | (9<<8)).#def
5cd0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ce0: 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20  RAINT_ROWID     
5cf0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5d00: 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a  RAINT |(10<<8)).
5d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d20: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41  OTICE_RECOVER_WA
5d30: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e  L      (SQLITE_N
5d40: 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a  OTICE | (1<<8)).
5d50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
5d60: 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f  OTICE_RECOVER_RO
5d70: 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e  LLBACK (SQLITE_N
5d80: 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a  OTICE | (2<<8)).
5d90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57  #define SQLITE_W
5da0: 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58  ARNING_AUTOINDEX
5db0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57         (SQLITE_W
5dc0: 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29  ARNING | (1<<8))
5dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5de0: 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20  AUTH_USER       
5df0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5e00: 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AUTH | (1<<8)).#
5e10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
5e20: 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c  _LOAD_PERMANENTL
5e30: 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b  Y     (SQLITE_OK
5e40: 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (1<<8))../*.*
5e50: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
5e60: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
5e70: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
5e80: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
5e90: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
5ea0: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
5eb0: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
5ec0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
5ed0: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
5ee0: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
5ef0: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
5f00: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5f10: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
5f20: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
5f30: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
5f40: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
5f50: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
5f60: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5f70: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5f80: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
5f90: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
5fa0: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
5fb0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
5fc0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
5fd0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
5fe0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5ff0: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
6000: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6010: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6020: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
6030: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
6040: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
6050: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6060: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
6070: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
6080: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
6090: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60a0: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
60b0: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
60c0: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
60d0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
60e0: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
60f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6100: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
6110: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6120: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6130: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59  LITE_OPEN_MEMORY
6140: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6150: 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00080  /* Ok for
6160: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6170: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6180: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
6190: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
61a0: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* VFS on
61b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
61c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
61d0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
61e0: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
61f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6200: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
6210: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
6220: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
6230: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6240: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
6250: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
6260: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
6270: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6280: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
6290: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
62a0: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
62b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
62c0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
62d0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
62e0: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
62f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6300: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
6310: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
6320: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
6330: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
6340: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
6350: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
6360: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
6370: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6380: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6390: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
63a0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
63b0: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
63c0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
63d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
63e0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
63f0: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
6400: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
6410: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6420: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6430: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
6440: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
6450: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
6460: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
6470: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6480: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
6490: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
64a0: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
64b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
64c0: 4c 49 54 45 5f 4f 50 45 4e 5f 46 49 4c 45 50 52  LITE_OPEN_FILEPR
64d0: 4f 54 45 43 54 49 4f 4e 5f 4d 41 53 4b 20 20 20  OTECTION_MASK   
64e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
64f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6500: 30 30 37 30 30 30 30 30 0a 0a 2f 2a 20 52 65 73  00700000../* Res
6510: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
6520: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6530: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
6540: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
6550: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
6560: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
6570: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
6580: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
6590: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
65a0: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
65b0: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
65c0: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
65d0: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65   vector of these
65e0: 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65  .** bit values e
65f0: 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68  xpressing I/O ch
6600: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66  aracteristics of
6610: 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67   the mass storag
6620: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
6630: 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20   holds the file 
6640: 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
6650: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
6660: 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a   refers to..**.*
6670: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
6680: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
6690: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
66a0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
66b0: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
66c0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
66d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
66e0: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
66f0: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
6700: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
6710: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
6720: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
6730: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
6740: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
6750: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
6760: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
6770: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
6780: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
6790: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
67a0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
67b0: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
67c0: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
67d0: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
67e0: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
67f0: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
6800: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
6810: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
6820: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
6830: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
6840: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
6850: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
6860: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
6870: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
6880: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
6890: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
68a0: 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51  Write().  The SQ
68b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
68c0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70  SAFE_OVERWRITE p
68d0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
68e0: 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f  at.** after rebo
68f0: 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ot following a c
6900: 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f  rash or power lo
6910: 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74  ss, the only byt
6920: 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20  es in a.** file 
6930: 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65  that were writte
6940: 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  n at the applica
6950: 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74  tion level might
6960: 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a   have changed.**
6970: 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65   and that adjace
6980: 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62  nt bytes, even b
6990: 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20  ytes within the 
69a0: 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a  same sector are.
69b0: 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ** guaranteed to
69c0: 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20   be unchanged.  
69d0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
69e0: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
69f0: 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69  N_OPEN.** flag i
6a00: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 61 20  ndicates that a 
6a10: 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64  file cannot be d
6a20: 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e  eleted when open
6a30: 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45  .  The.** SQLITE
6a40: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
6a50: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20   flag indicates 
6a60: 74 68 61 74 20 74 68 65 20 66 69 6c 65 20 69 73  that the file is
6a70: 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79   on.** read-only
6a80: 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f   media and canno
6a90: 74 20 62 65 20 63 68 61 6e 67 65 64 20 65 76 65  t be changed eve
6aa0: 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73 20 77  n by processes w
6ab0: 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20  ith.** elevated 
6ac0: 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23  privileges..*/.#
6ad0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ae0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
6af0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b00: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
6b10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6b20: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
6b30: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
6b40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b50: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
6b60: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b70: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
6b80: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
6b90: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6ba0: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
6bb0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6bc0: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
6bd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
6be0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6bf0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
6c00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6c10: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
6c20: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6c30: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
6c40: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
6c50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c60: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
6c70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c80: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
6c90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6ca0: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
6cb0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
6cc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6cd0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
6ce0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6cf0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
6d00: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6d10: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
6d20: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
6d30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6d40: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
6d50: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
6d60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6d70: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6d80: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
6d90: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
6da0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  e SQLITE_IOCAP_I
6db0: 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20  MMUTABLE        
6dc0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
6dd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6de0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
6df0: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  evels.**.** SQLi
6e00: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
6e10: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6e20: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6e30: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
6e40: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
6e50: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
6e60: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
6e70: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
6e80: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6e90: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
6ea0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6eb0: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
6ec0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6ed0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
6ee0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
6ef0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
6f00: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
6f10: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
6f20: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
6f30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6f40: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
6f50: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
6f60: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
6f70: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a  on Type Flags.**
6f80: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
6f90: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
6fa0: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
6fb0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
6fc0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6fd0: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
6fe0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
6ff0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
7000: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
7010: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
7020: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
7030: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
7040: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
7050: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
7060: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
7070: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
7080: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
7090: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
70a0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
70b0: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
70c0: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
70d0: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
70e0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
70f0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7100: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
7110: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
7120: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
7130: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
7140: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
7150: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7160: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
7170: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
7180: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
7190: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
71a0: 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20  )..**.** Do not 
71b0: 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49  confuse the SQLI
71c0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
71d0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
71e0: 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74  ULL flags.** wit
71f0: 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79  h the [PRAGMA sy
7200: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41  nchronous]=NORMA
7210: 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79  L and [PRAGMA sy
7220: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a  nchronous]=FULL.
7230: 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68  ** settings.  Th
7240: 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70  e [synchronous p
7250: 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65  ragma] determine
7260: 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  s when calls to 
7270: 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53  the.** xSync VFS
7280: 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e   method occur an
7290: 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72  d applies unifor
72a0: 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70  mly across all p
72b0: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65  latforms..** The
72c0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
72d0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
72e0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64  YNC_FULL flags d
72f0: 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20  etermine how.** 
7300: 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67  energetic or rig
7310: 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75  orous or forcefu
7320: 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61  l the sync opera
7330: 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a  tions are and.**
7340: 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66   only make a dif
7350: 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f  ference on Mac O
7360: 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75  SX for the defau
7370: 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a  lt SQLite code..
7380: 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20  ** (Third-party 
7390: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
73a0: 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d  ons might also m
73b0: 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
73c0: 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
73d0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
73e0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
73f0: 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e  C_FULL, but amon
7400: 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69  g the.** operati
7410: 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76  ng systems nativ
7420: 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79  ely supported by
7430: 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61   SQLite, only Ma
7440: 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61  c OSX.** cares a
7450: 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65  bout the differe
7460: 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65  nce.).*/.#define
7470: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7480: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
7490: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
74a0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
74b0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
74c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
74d0: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
74e0: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
74f0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7500: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
7510: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  andle.**.** An [
7520: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7530: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
7540: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
7550: 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
7560: 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66  _vfs | OS interf
7570: 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64  ace layer].  Ind
7580: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
7590: 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  face.** implemen
75a0: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
75b0: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
75c0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
75d0: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
75e0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
75f0: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
7600: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
7610: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
7620: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
7630: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7640: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
7650: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
7660: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
7670: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
7680: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
7690: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
76a0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
76b0: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
76c0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
76d0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
76e0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
76f0: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
7700: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
7710: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
7720: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
7730: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7740: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
7750: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
7760: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
7770: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
7780: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7790: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
77a0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
77b0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
77c0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
77d0: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
77e0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
77f0: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
7800: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
7810: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
7820: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
7830: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
7840: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
7850: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
7860: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
7870: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
7880: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
7890: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
78a0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
78b0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ct..**.** If the
78c0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
78d0: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73  pen] method sets
78e0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
78f0: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
7900: 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d  nt .** to a non-
7910: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
7920: 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  en the sqlite3_i
7930: 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65  o_methods.xClose
7940: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62   method.** may b
7950: 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69  e invoked even i
7960: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
7970: 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74  fs.xOpen] report
7980: 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65  ed that it faile
7990: 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20  d.  The.** only 
79a0: 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61  way to prevent a
79b0: 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20   call to xClose 
79c0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
79d0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  ed [sqlite3_vfs.
79e0: 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72  xOpen].** is for
79f0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7a00: 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20  s.xOpen] to set 
7a10: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
7a20: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
7a30: 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  t.** to NULL..**
7a40: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
7a50: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
7a60: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
7a70: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7a80: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
7a90: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
7aa0: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
7ab0: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
7ac0: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nc()..** The sec
7ad0: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20  ond choice is a 
7ae0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
7af0: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53  ullsync.  The [S
7b00: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
7b10: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79  NLY].** flag may
7b20: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69   be ORed in to i
7b30: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c  ndicate that onl
7b40: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68  y the data of th
7b50: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f  e file.** and no
7b60: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
7b70: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a  s to be synced..
7b80: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  **.** The intege
7b90: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
7ba0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
7bb0: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
7bc0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7bd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
7be0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7bf0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
7c00: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7c10: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
7c20: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7c30: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
7c40: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7c50: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7c60: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
7c70: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
7c80: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
7c90: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
7ca0: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78  e lock..** The x
7cb0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
7cc0: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
7cd0: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
7ce0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7cf0: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
7d00: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
7d10: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
7d20: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
7d30: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
7d40: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
7d50: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
7d60: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
7d70: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
7d80: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
7d90: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
7da0: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erwise..**.** Th
7db0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
7dc0: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
7dd0: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
7de0: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
7df0: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
7e00: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
7e10: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
7e20: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
7e30: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
7e40: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
7e50: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
7e60: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
7e70: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e  ment is an.** in
7e80: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54  teger opcode.  T
7e90: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
7ea0: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
7eb0: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20  ointer intended 
7ec0: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  to.** point to a
7ed0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
7ee0: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
7ef0: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
7f00: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
7f10: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
7f20: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
7f30: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
7f40: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
7f50: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
7f60: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
7f70: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
7f80: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
7f90: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
7fa0: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
7fb0: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
7fc0: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
7fd0: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
7fe0: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
7ff0: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
8000: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
8010: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
8020: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f  e reserves all o
8030: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
8040: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
8050: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65   use..** A [file
8060: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
8070: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64   | list of opcod
8080: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30  es] less than 10
8090: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  0 is available..
80a0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
80b0: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75  that define a cu
80c0: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f  stom xFileContro
80d0: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  l method should 
80e0: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67  use opcodes.** g
80f0: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
8100: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
8110: 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65  ts.  VFS impleme
8120: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a  ntations should.
8130: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
8140: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20  E_NOTFOUND] for 
8150: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8160: 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64  odes that they d
8170: 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69  o not.** recogni
8180: 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ze..**.** The xS
8190: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
81a0: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
81b0: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
81c0: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
81d0: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
81e0: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
81f0: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
8200: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
8210: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
8220: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
8230: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
8240: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
8250: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
8260: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
8270: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
8280: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
8290: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
82a0: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
82b0: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
82c0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
82d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
82e0: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
82f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8300: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
8310: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8320: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
8330: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8340: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
8350: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8360: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
8370: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8380: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
8390: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
83a0: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
83b0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
83c0: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
83d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
83e0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
83f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8400: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8410: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8420: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
8430: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  AL].** <li> [SQL
8440: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
8450: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 5d  TABLE_WHEN_OPEN]
8460: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8470: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
8480: 5f 4f 56 45 52 57 52 49 54 45 5d 0a 2a 2a 20 3c  _OVERWRITE].** <
8490: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
84a0: 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 0a 2a 2a 20  P_IMMUTABLE].** 
84b0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
84c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
84d0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
84e0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
84f0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
8500: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
8510: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8520: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
8530: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
8540: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
8550: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
8560: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
8570: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
8580: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
8590: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
85a0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
85b0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
85c0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
85d0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
85e0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
85f0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
8600: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
8610: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
8620: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
8630: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
8640: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
8650: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
8660: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
8670: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
8680: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
8690: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
86a0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
86b0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
86c0: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
86d0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
86e0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
86f0: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
8700: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
8710: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
8720: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
8730: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
8740: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
8750: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
8760: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
8770: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
8780: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
8790: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
87a0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
87b0: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
87c0: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
87d0: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
87e0: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
87f0: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
8800: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
8810: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
8820: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
8830: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8840: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
8850: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
8860: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
8870: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
8880: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8890: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
88a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
88b0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
88c0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
88d0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
88e0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
88f0: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
8900: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8910: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8920: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
8930: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8940: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8950: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
8960: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
8970: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
8980: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
8990: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
89a0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
89b0: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
89c0: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
89d0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
89e0: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
89f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8a00: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
8a10: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
8a20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8a30: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
8a40: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
8a50: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
8a60: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
8a70: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
8a80: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
8a90: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8aa0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
8ab0: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
8ac0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
8ad0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8ae0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8af0: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
8b00: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
8b10: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
8b20: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
8b30: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
8b40: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
8b50: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
8b60: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
8b70: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
8b80: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
8b90: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
8ba0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8bb0: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
8bc0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8bd0: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
8be0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8bf0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8c00: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e  ersion 2 */.  in
8c10: 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69  t (*xFetch)(sqli
8c20: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8c30: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8c40: 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a  int iAmt, void *
8c50: 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  *pp);.  int (*xU
8c60: 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  nfetch)(sqlite3_
8c70: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8c80: 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64  nt64 iOfst, void
8c90: 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f   *p);.  /* Metho
8ca0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8cb0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  id for version 3
8cc0: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
8cd0: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
8ce0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
8cf0: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
8d00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8d10: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
8d20: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
8d30: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
8d40: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8d50: 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72  des} {file contr
8d60: 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ol opcode}.**.**
8d70: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
8d80: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
8d90: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
8da0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8db0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
8dc0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8dd0: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
8de0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8df0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
8e00: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
8e10: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  <ul>.** <li>[[SQ
8e20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
8e30: 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  TATE]].** The [S
8e40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
8e50: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
8e60: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
8e70: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
8e80: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
8e90: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8ea0: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
8eb0: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
8ec0: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
8ed0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
8ee0: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
8ef0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
8f00: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
8f10: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
8f20: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
8f30: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
8f40: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
8f50: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
8f60: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
8f70: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
8f80: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
8f90: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
8fa0: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
8fb0: 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
8fc0: 6c 65 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49  le when the SQLI
8fd0: 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69  TE_TEST.** compi
8fe0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
8ff0: 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  s used..**.** <l
9000: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9010: 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20  _SIZE_HINT]].** 
9020: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9030: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63  L_SIZE_HINT] opc
9040: 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53  ode is used by S
9050: 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68  QLite to give th
9060: 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61  e VFS.** layer a
9070: 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72   hint of how lar
9080: 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
9090: 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74  file will grow t
90a0: 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a  o be during the.
90b0: 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  ** current trans
90c0: 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69  action.  This hi
90d0: 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e  nt is not guaran
90e0: 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72  teed to be accur
90f0: 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73  ate but it.** is
9100: 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54   often close.  T
9110: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46  he underlying VF
9120: 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74  S might choose t
9130: 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61  o preallocate da
9140: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73  tabase.** file s
9150: 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68  pace based on th
9160: 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72  is hint in order
9170: 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20   to help writes 
9180: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
9190: 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74  ** file run fast
91a0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  er..**.** <li>[[
91b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
91c0: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
91d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
91e0: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
91f0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
9200: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
9210: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
9220: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
9230: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
9240: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
9250: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
9260: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
9270: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
9280: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
9290: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
92a0: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
92b0: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
92c0: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
92d0: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
92e0: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
92f0: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
9300: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
9310: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
9320: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
9330: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
9340: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
9350: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
9360: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
9370: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
9380: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
9390: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
93a0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
93b0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
93c0: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
93d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
93e0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
93f0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
9400: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
9410: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
9420: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
9430: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
9440: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9450: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9460: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
9470: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
9480: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a  NAL_POINTER]..**
9490: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
94a0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
94b0: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
94c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
94d0: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f  URNAL_POINTER] o
94e0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
94f0: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9500: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9510: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9520: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
9530: 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69  h the journal fi
9540: 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68  le (either.** th
9550: 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  e [rollback jour
9560: 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69  nal] or the [wri
9570: 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66  te-ahead log]) f
9580: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
9590: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
95a0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
95b0: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
95c0: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a  FILE_POINTER]..*
95d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
95e0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
95f0: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e  TTED]].** No lon
9600: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a  ger in use..**.*
9610: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9620: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54  CNTL_SYNC]].** T
9630: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9640: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
9650: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9660: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20  nally by SQLite 
9670: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74  and.** sent to t
9680: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65  he VFS immediate
9690: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53  ly before the xS
96a0: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  ync method is in
96b0: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61  voked on a.** da
96c0: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63  tabase file desc
96d0: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74  riptor. Or, if t
96e0: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
96f0: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a  is not invoked .
9700: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75  ** because the u
9710: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72  ser has configur
9720: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a  ed SQLite with .
9730: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  ** [PRAGMA synch
9740: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
9750: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
9760: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69   it is invoked i
9770: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74  n place .** of t
9780: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e  he xSync method.
9790: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20   In most cases, 
97a0: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  the pointer argu
97b0: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68  ment passed with
97c0: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  .** this file-co
97d0: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48  ntrol is NULL. H
97e0: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64  owever, if the d
97f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
9800: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20  being synced.** 
9810: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c  as part of a mul
9820: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d  ti-database comm
9830: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74  it, the argument
9840: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c   points to a nul
9850: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
9860: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
9870: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
9880: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c  s master-journal
9890: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65   file name. VFSe
98a0: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f  s that .** do no
98b0: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
98c0: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  al should silent
98d0: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
98e0: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
98f0: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ons .** should n
9900: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
9910: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9920: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
9930: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
9940: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68  y .** disrupt th
9950: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
9960: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
9970: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
9980: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
9990: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
99a0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
99b0: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TWO]].** The [SQ
99c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
99d0: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f  T_PHASETWO] opco
99e0: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
99f0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
9a00: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74  Lite.** and sent
9a10: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65   to the VFS afte
9a20: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
9a30: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  has been committ
9a40: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ed immediately.*
9a50: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65  * but before the
9a60: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c   database is unl
9a70: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61  ocked. VFSes tha
9a80: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  t do not need th
9a90: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f  is signal.** sho
9aa0: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
9ab0: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
9ac0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
9ad0: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a  ould not call.**
9ae0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9af0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9b00: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9b10: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
9b20: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61  pt the .** opera
9b30: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9b40: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9b50: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9b60: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9b70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9b80: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
9b90: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9ba0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9bb0: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
9bc0: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
9bd0: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
9be0: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
9bf0: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
9c00: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
9c10: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
9c20: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
9c30: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
9c40: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
9c50: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
9c60: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
9c70: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
9c80: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
9c90: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
9ca0: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
9cb0: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
9cc0: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
9cd0: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
9ce0: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
9cf0: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
9d00: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
9d10: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
9d20: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
9d30: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
9d40: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
9d50: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
9d60: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
9d70: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
9d80: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
9d90: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
9da0: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
9db0: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
9dc0: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
9dd0: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
9de0: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
9df0: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
9e00: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
9e10: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
9e20: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
9e30: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
9e40: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
9e50: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
9e60: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
9e70: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
9e80: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 6e  integer is the n
9e90: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
9ea0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
9eb0: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
9ec0: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
9ed0: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
9ee0: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
9ef0: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
9f00: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
9f10: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
9f20: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
9f30: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
9f40: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
9f50: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
9f60: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
9f70: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
9f80: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
9f90: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
9fa0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
9fb0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
9fc0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9fd0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
9fe0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9ff0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
a000: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a010: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
a020: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
a030: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
a040: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
a050: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
a060: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
a070: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
a080: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
a090: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
a0a0: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
a0b0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
a0c0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
a0d0: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
a0e0: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
a0f0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
a100: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
a110: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
a120: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
a130: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
a140: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
a150: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
a160: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
a170: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
a180: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
a190: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
a1a0: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
a1b0: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
a1c0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
a1d0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
a1e0: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
a1f0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
a200: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
a210: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
a220: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
a230: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
a240: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
a250: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
a260: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a270: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
a280: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a290: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
a2a0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
a2b0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
a2c0: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
a2d0: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
a2e0: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
a2f0: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
a300: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
a310: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
a320: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a330: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a340: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a350: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a360: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
a370: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
a380: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a390: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
a3a0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
a3b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a3c0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a3d0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
a3e0: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
a3f0: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
a400: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
a410: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
a420: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
a430: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
a440: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
a450: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
a460: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
a470: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
a480: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
a490: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
a4a0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
a4b0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
a4c0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a4d0: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
a4e0: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
a4f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
a500: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
a510: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
a520: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
a530: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
a540: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
a550: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
a560: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
a570: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
a580: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
a590: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
a5a0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a5b0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
a5c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a5d0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
a5e0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a5f0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
a600: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
a610: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
a620: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
a630: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
a640: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
a650: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
a660: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
a670: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
a680: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
a690: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
a6a0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
a6b0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
a6c0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
a6d0: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
a6e0: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
a6f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a700: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a710: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a720: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
a730: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
a740: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
a750: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
a760: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
a770: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
a780: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
a790: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
a7a0: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
a7b0: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
a7c0: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
a7d0: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
a7e0: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
a7f0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
a800: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
a810: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
a820: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
a830: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
a840: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
a850: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a860: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
a870: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
a880: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
a890: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
a8a0: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
a8b0: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
a8c0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
a8d0: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
a8e0: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
a8f0: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
a900: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
a910: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
a920: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
a930: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
a940: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
a950: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
a960: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
a970: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
a980: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
a990: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
a9a0: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
a9b0: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
a9c0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a9d0: 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54  _FCNTL_VFS_POINT
a9e0: 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ER]].** ^The [SQ
a9f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
aa00: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66  OINTER] opcode f
aa10: 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74  inds a pointer t
aa20: 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a  o the top-level.
aa30: 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65  ** [VFSes] curre
aa40: 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28  ntly in use.  ^(
aa50: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69  The argument X i
aa60: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c  n.** sqlite3_fil
aa70: 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c  e_control(db,SQL
aa80: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
aa90: 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65  INTER,X) must be
aaa0: 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71  .** of type "[sq
aab0: 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20  lite3_vfs] **". 
aac0: 20 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69   This opcodes wi
aad0: 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20  ll set *X.** to 
aae0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
aaf0: 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29   top-level VFS.)
ab00: 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65  ^.** ^When there
ab10: 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46   are multiple VF
ab20: 53 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73  S shims in the s
ab30: 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64  tack, this opcod
ab40: 65 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75  e finds the.** u
ab50: 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f  pper-most shim o
ab60: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
ab70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ab80: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
ab90: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
aba0: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
abb0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
abc0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
abd0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
abe0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
abf0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
ac00: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
ac10: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
ac20: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
ac30: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
ac40: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
ac50: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
ac60: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
ac70: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ac80: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
ac90: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
aca0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
acb0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
acc0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
acd0: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
ace0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
acf0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
ad00: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
ad10: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
ad20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
ad30: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
ad40: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
ad50: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
ad60: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
ad70: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
ad80: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
ad90: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
ada0: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
adb0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
adc0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
add0: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
ade0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
adf0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
ae00: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
ae10: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
ae20: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
ae30: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
ae40: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
ae50: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
ae60: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
ae70: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
ae80: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
ae90: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
aea0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
aeb0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
aec0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
aed0: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
aee0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
aef0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
af00: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
af10: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
af20: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
af30: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
af40: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
af50: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
af60: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
af70: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
af80: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
af90: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
afa0: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
afb0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
afc0: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
afd0: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
afe0: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
aff0: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
b000: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
b010: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
b020: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
b030: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
b040: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
b050: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
b060: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
b070: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
b080: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
b090: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
b0a0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
b0b0: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
b0c0: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
b0d0: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
b0e0: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
b0f0: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
b100: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
b110: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
b120: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
b130: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
b140: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
b150: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
b160: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
b170: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
b180: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
b190: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
b1a0: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
b1b0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
b1c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b1d0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
b1e0: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
b1f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
b200: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
b210: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
b220: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
b230: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
b240: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
b250: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
b260: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
b270: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
b280: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
b290: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
b2a0: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
b2b0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
b2c0: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
b2d0: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
b2e0: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
b2f0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
b300: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
b310: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
b320: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
b330: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
b340: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
b350: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
b360: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
b370: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
b380: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
b390: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
b3a0: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
b3b0: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
b3c0: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
b3d0: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
b3e0: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
b3f0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
b400: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
b410: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
b420: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
b430: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
b440: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
b450: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
b460: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
b470: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
b480: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b490: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
b4a0: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
b4b0: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
b4c0: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
b4d0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
b4e0: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
b4f0: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
b500: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
b510: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
b520: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
b530: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
b540: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
b550: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
b560: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
b570: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
b580: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
b590: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
b5a0: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b5b0: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
b5c0: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
b5d0: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
b5e0: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
b5f0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b600: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b610: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
b620: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
b630: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
b640: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
b650: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
b660: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
b670: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b680: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b690: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
b6a0: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b6b0: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
b6c0: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
b6d0: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
b6e0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b6f0: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
b700: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
b710: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
b720: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b730: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
b740: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
b750: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
b760: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
b770: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
b780: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
b790: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
b7a0: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
b7b0: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
b7c0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
b7d0: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
b7e0: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
b7f0: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
b800: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
b810: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
b820: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
b830: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
b840: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
b850: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
b860: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
b870: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
b880: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
b890: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
b8a0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
b8b0: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
b8c0: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
b8d0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b8e0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
b8f0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b900: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
b910: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
b920: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
b930: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
b940: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
b950: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
b960: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
b970: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
b980: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
b990: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
b9a0: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
b9b0: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
b9c0: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
b9d0: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
b9e0: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
b9f0: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
ba00: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
ba10: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
ba20: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
ba30: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
ba40: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
ba50: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
ba60: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
ba70: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
ba80: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
ba90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
baa0: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
bab0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
bac0: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
bad0: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
bae0: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
baf0: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
bb00: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
bb10: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
bb20: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
bb30: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
bb40: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
bb50: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
bb60: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
bb70: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
bb80: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
bb90: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
bba0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bbb0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bbc0: 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  GET_HANDLE]].** 
bbd0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bbe0: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
bbf0: 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  LE] opcode can b
bc00: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
bc10: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
bc20: 6e 67 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68  ng native file h
bc30: 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 74 65 64  andle associated
bc40: 20 77 69 74 68 20 61 20 66 69 6c 65 20 68 61 6e   with a file han
bc50: 64 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 0a  dle.  This file.
bc60: 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  ** control inter
bc70: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
bc80: 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 65 72 20  nt as a pointer 
bc90: 74 6f 20 61 20 6e 61 74 69 76 65 20 66 69 6c 65  to a native file
bca0: 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77   handle and.** w
bcb0: 72 69 74 65 73 20 74 68 65 20 72 65 73 75 6c 74  rites the result
bcc0: 69 6e 67 20 76 61 6c 75 65 20 74 68 65 72 65 2e  ing value there.
bcd0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bce0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bcf0: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
bd00: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bd10: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
bd20: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
bd30: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
bd40: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
bd50: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
bd60: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
bd70: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
bd80: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
bd90: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
bda0: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
bdb0: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
bdc0: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
bdd0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
bde0: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
bdf0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
be00: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
be10: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
be20: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
be30: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
be40: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
be50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
be60: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
be70: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
be80: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
be90: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
bea0: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
beb0: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
bec0: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
bed0: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
bee0: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
bef0: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
bf00: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
bf10: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
bf20: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
bf30: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
bf40: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
bf50: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
bf60: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
bf70: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
bf80: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
bf90: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
bfa0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bfb0: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
bfc0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bfd0: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
bfe0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
bff0: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
c000: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
c010: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
c020: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
c030: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
c040: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
c050: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
c060: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
c070: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
c080: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
c090: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
c0a0: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
c0b0: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
c0c0: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
c0d0: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
c0e0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
c0f0: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
c100: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20  is opcode.  .** 
c110: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
c120: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
c130: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
c140: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
c150: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
c160: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
c170: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
c180: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
c190: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c1a0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
c1b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
c1c0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
c1d0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
c1e0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
c1f0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
c200: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
c210: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
c220: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
c230: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
c240: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
c250: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
c260: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
c270: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
c280: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
c290: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c2a0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
c2b0: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
c2c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c2d0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
c2e0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
c2f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c300: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
c310: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
c320: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c330: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
c340: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
c350: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c360: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
c370: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
c380: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c390: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
c3a0: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
c3b0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c3c0: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
c3d0: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
c3e0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
c3f0: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
c400: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
c410: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
c420: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
c430: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
c440: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
c450: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
c460: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
c470: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
c480: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
c490: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
c4a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
c4b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c4c0: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
c4d0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
c4e0: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
c4f0: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
c500: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
c510: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
c520: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  23.#define SQLIT
c530: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
c540: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  K              2
c550: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c560: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20  _FCNTL_ZIPVFS   
c570: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
c580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c590: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20  FCNTL_RBU       
c5a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a               26.
c5b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c5c0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
c5d0: 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a 23              27.#
c5e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c5f0: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
c600: 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 23 64  TER        28.#d
c610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c620: 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e  TL_WIN32_GET_HAN
c630: 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64 65  DLE       29.#de
c640: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c650: 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20 20 20  L_PDB           
c660: 20 20 20 20 20 20 20 20 20 33 30 0a 0a 2f 2a 20           30../* 
c670: 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73  deprecated names
c680: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
c690: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
c6a0: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
c6b0: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
c6c0: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
c6d0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
c6e0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
c6f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
c700: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
c710: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
c720: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
c730: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
c740: 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a  _LAST_ERRNO.../*
c750: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
c760: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
c770: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
c780: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
c790: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
c7a0: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
c7b0: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
c7c0: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
c7d0: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
c7e0: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
c7f0: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
c800: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
c810: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
c820: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
c830: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
c840: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
c850: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
c860: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
c870: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
c880: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
c890: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
c8a0: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
c8b0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
c8c0: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
c8d0: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
c8e0: 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74  EF: Loadable Ext
c8f0: 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a  ension Thunk.**.
c900: 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
c910: 74 68 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74  the opaque sqlit
c920: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
c930: 73 74 72 75 63 74 75 72 65 20 69 73 20 70 61 73  structure is pas
c940: 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68  sed as.** the th
c950: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
c960: 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66   entry points of
c970: 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e   [loadable exten
c980: 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a  sions].  This.**
c990: 20 73 74 72 75 63 74 75 72 65 20 6d 75 73 74 20   structure must 
c9a0: 62 65 20 74 79 70 65 64 65 66 65 64 20 69 6e 20  be typedefed in 
c9b0: 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72  order to work ar
c9c0: 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61  ound compiler wa
c9d0: 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d  rnings.** on som
c9e0: 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a  e platforms..*/.
c9f0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
ca00: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
ca10: 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  nes sqlite3_api_
ca20: 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a  routines;../*.**
ca30: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
ca40: 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a  terface Object.*
ca50: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
ca60: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
ca70: 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  vfs object defin
ca80: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
ca90: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
caa0: 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20  SQLite core and 
cab0: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f  the underlying o
cac0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e  perating system.
cad0: 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69    The "vfs".** i
cae0: 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
caf0: 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20  e object stands 
cb00: 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c  for "virtual fil
cb10: 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a  e system".  See.
cb20: 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46  ** the [VFS | VF
cb30: 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  S documentation]
cb40: 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66   for further inf
cb50: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
cb60: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
cb70: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
cb80: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
cb90: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
cba0: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
cbb0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
cbc0: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
cbd0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
cbe0: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
cbf0: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
cc00: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
cc10: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
cc20: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
cc30: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
cc40: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
cc50: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
cc60: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
cc70: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
cc80: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
cc90: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
cca0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
ccb0: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
ccc0: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
ccd0: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
cce0: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
ccf0: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
cd00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
cd10: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
cd20: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
cd30: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
cd40: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
cd50: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
cd60: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
cd70: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
cd80: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
cd90: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
cda0: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
cdb0: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
cdc0: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
cdd0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
cde0: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
cdf0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
ce00: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
ce10: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
ce20: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
ce30: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
ce40: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
ce50: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
ce60: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
ce70: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
ce80: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
ce90: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
cea0: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
ceb0: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
cec0: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
ced0: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
cee0: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
cef0: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
cf00: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
cf10: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
cf20: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
cf30: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
cf40: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
cf50: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
cf60: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
cf70: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
cf80: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
cf90: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
cfa0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
cfb0: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
cfc0: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
cfd0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
cfe0: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
cff0: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
d000: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
d010: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
d020: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
d030: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
d040: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
d050: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
d060: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
d070: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73  dules..**.** [[s
d080: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
d090: 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  ]].** ^SQLite gu
d0a0: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
d0b0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
d0c0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
d0d0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
d0e0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
d0f0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
d100: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
d110: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
d120: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
d130: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
d140: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
d150: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
d160: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
d170: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
d180: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
d190: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
d1a0: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
d1b0: 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72  ** 11 alphanumer
d1c0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
d1d0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
d1e0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
d1f0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
d200: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
d210: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
d220: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
d230: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
d240: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
d250: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
d260: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
d270: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
d280: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
d290: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
d2a0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
d2b0: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
d2c0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
d2d0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
d2e0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
d2f0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
d300: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
d310: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
d320: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
d330: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
d340: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
d350: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
d360: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
d370: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
d380: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
d390: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
d3a0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
d3b0: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
d3c0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
d3d0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
d3e0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
d3f0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
d400: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
d410: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
d420: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
d430: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
d440: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
d450: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
d460: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
d470: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
d480: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
d490: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
d4a0: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
d4b0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
d4c0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
d4d0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
d4e0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
d4f0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
d500: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
d510: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
d520: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
d530: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
d540: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
d550: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
d560: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
d570: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
d580: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
d590: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
d5a0: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
d5b0: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
d5c0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
d5d0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
d5e0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
d5f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
d600: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
d610: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
d620: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
d630: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
d640: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
d650: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
d660: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
d670: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d680: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
d690: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d6a0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
d6b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d6c0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
d6d0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
d6e0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
d6f0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
d700: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
d710: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
d720: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
d730: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
d740: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
d750: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
d760: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
d770: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
d780: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
d790: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
d7a0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
d7b0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
d7c0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
d7d0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
d7e0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
d7f0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
d800: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
d810: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
d820: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
d830: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
d840: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
d850: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
d860: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
d870: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
d880: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
d890: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
d8a0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
d8b0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
d8c0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
d8d0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
d8e0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
d8f0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
d900: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
d910: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
d920: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
d930: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
d940: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
d950: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
d960: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
d970: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
d980: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
d990: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
d9a0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
d9b0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
d9c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
d9d0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
d9e0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
d9f0: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
da00: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
da10: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
da20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
da30: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
da40: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
da50: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
da60: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
da70: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
da80: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
da90: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
daa0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
dab0: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
dac0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
dad0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
dae0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
daf0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
db00: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
db10: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
db20: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
db30: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
db40: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
db50: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
db60: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
db70: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
db80: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
db90: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
dba0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
dbb0: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
dbc0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
dbd0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
dbe0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
dbf0: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
dc00: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
dc10: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
dc20: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
dc30: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
dc40: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
dc50: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
dc60: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
dc70: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
dc80: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
dc90: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
dca0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
dcb0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
dcc0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
dcd0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
dce0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
dcf0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
dd00: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
dd10: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
dd20: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
dd30: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
dd40: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
dd50: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
dd60: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
dd70: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
dd80: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
dd90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
dda0: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
ddb0: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
ddc0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
ddd0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
dde0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
ddf0: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
de00: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
de10: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
de20: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
de30: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
de40: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
de50: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
de60: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
de70: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
de80: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
de90: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
dea0: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b  en call..**.** [
deb0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63  [sqlite3_vfs.xAc
dec0: 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66  cess]].** ^The f
ded0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
dee0: 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62   xAccess() may b
def0: 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  e [SQLITE_ACCESS
df00: 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74  _EXISTS].** to t
df10: 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73  est for the exis
df20: 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c  tence of a file,
df30: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
df40: 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f  SS_READWRITE] to
df50: 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72  .** test whether
df60: 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61   a file is reada
df70: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
df80: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
df90: 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20  ESS_READ].** to 
dfa0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
dfb0: 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20  ile is at least 
dfc0: 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20  readable.   The 
dfd0: 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a  file can be a.**
dfe0: 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
dff0: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  * ^SQLite will a
e000: 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61  lways allocate a
e010: 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61  t least mxPathna
e020: 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74  me+1 bytes for t
e030: 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66  he.** output buf
e040: 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d  fer xFullPathnam
e050: 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69  e.  The exact si
e060: 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74  ze of the output
e070: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c   buffer.** is al
e080: 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70  so passed as a p
e090: 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68  arameter to both
e0a0: 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68    methods. If th
e0b0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
e0c0: 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20  ** is not large 
e0d0: 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f  enough, [SQLITE_
e0e0: 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64  CANTOPEN] should
e0f0: 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69   be returned. Si
e100: 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68  nce this is.** h
e110: 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61  andled as a fata
e120: 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74  l error by SQLit
e130: 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74  e, vfs implement
e140: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e  ations should en
e150: 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65  deavor.** to pre
e160: 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74  vent this by set
e170: 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20  ting mxPathname 
e180: 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c  to a sufficientl
e190: 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a  y large value..*
e1a0: 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  *.** The xRandom
e1b0: 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29  ness(), xSleep()
e1c0: 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  , xCurrentTime()
e1d0: 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69  , and xCurrentTi
e1e0: 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74  meInt64().** int
e1f0: 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20  erfaces are not 
e200: 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20  strictly a part 
e210: 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65  of the filesyste
e220: 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a  m, but they are.
e230: 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  ** included in t
e240: 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65  he VFS structure
e250: 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73   for completenes
e260: 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  s..** The xRando
e270: 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e  mness() function
e280: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74   attempts to ret
e290: 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73  urn nBytes bytes
e2a0: 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c  .** of good-qual
e2b0: 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69  ity randomness i
e2c0: 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72  nto zOut.  The r
e2d0: 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a  eturn value is.*
e2e0: 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d  * the actual num
e2f0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20  ber of bytes of 
e300: 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
e310: 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65  ned..** The xSle
e320: 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73  ep() method caus
e330: 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74  es the calling t
e340: 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66  hread to sleep f
e350: 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74  or at.** least t
e360: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63  he number of mic
e370: 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e  roseconds given.
e380: 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54    ^The xCurrentT
e390: 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  ime().** method 
e3a0: 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e  returns a Julian
e3b0: 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20   Day Number for 
e3c0: 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65  the current date
e3d0: 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20   and time as.** 
e3e0: 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
e3f0: 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20   value..** ^The 
e400: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
e410: 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  4() method retur
e420: 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65  ns, as an intege
e430: 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a  r, the Julian.**
e440: 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74   Day Number mult
e450: 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30  iplied by 864000
e460: 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f  00 (the number o
e470: 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69  f milliseconds i
e480: 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20  n .** a 24-hour 
e490: 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69  day).  .** ^SQLi
e4a0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
e4b0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
e4c0: 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65  4() method to ge
e4d0: 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  t the current.**
e4e0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69   date and time i
e4f0: 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73  f that method is
e500: 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69   available (if i
e510: 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20  Version is 2 or 
e520: 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20  .** greater and 
e530: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  the function poi
e540: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
e550: 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20  ) and will fall 
e560: 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72  back.** to xCurr
e570: 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75  entTime() if xCu
e580: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
e590: 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e   is unavailable.
e5a0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74  .**.** ^The xSet
e5b0: 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47  SystemCall(), xG
e5c0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
e5d0: 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43  and xNestSystemC
e5e0: 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73  all() interfaces
e5f0: 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64  .** are not used
e600: 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63   by the SQLite c
e610: 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69  ore.  These opti
e620: 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  onal interfaces 
e630: 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  are provided.** 
e640: 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f  by some VFSes to
e650: 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74   facilitate test
e660: 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63  ing of the VFS c
e670: 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69  ode. By overridi
e680: 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61  ng .** system ca
e690: 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f  lls with functio
e6a0: 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e  ns under its con
e6b0: 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f  trol, a test pro
e6c0: 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75  gram can.** simu
e6d0: 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20  late faults and 
e6e0: 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73  error conditions
e6f0: 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65   that would othe
e700: 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75  rwise be difficu
e710: 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69  lt.** or impossi
e720: 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20  ble to induce.  
e730: 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65  The set of syste
e740: 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e  m calls that can
e750: 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a   be overridden.*
e760: 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  * varies from on
e770: 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72  e VFS to another
e780: 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76  , and from one v
e790: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61  ersion of the sa
e7a0: 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a  me VFS to the.**
e7b0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
e7c0: 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68  ions that use th
e7d0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ese interfaces m
e7e0: 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20  ust be prepared 
e7f0: 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c  for any.** or al
e800: 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72  l of these inter
e810: 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c  faces to be NULL
e820: 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65   or for their be
e830: 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65  havior to change
e840: 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c  .** from one rel
e850: 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74  ease to the next
e860: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
e870: 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74  must not attempt
e880: 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e   to access.** an
e890: 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f  y of these metho
e8a0: 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69  ds if the iVersi
e8b0: 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73  on of the VFS is
e8c0: 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f   less than 3..*/
e8d0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
e8e0: 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69  sqlite3_vfs sqli
e8f0: 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66  te3_vfs;.typedef
e900: 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
e910: 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69  syscall_ptr)(voi
e920: 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  d);.struct sqlit
e930: 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69  e3_vfs {.  int i
e940: 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20  Version;        
e950: 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65      /* Structure
e960: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20   version number 
e970: 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f  (currently 3) */
e980: 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b  .  int szOsFile;
e990: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
e9a0: 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65  ize of subclasse
e9b0: 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a  d sqlite3_file *
e9c0: 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61  /.  int mxPathna
e9d0: 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  me;          /* 
e9e0: 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74  Maximum file pat
e9f0: 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a  hname length */.
ea00: 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70    sqlite3_vfs *p
ea10: 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65  Next;      /* Ne
ea20: 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46  xt registered VF
ea30: 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  S */.  const cha
ea40: 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20  r *zName;       
ea50: 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20  /* Name of this 
ea60: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
ea70: 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tem */.  void *p
ea80: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
ea90: 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20    /* Pointer to 
eaa0: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63  application-spec
eab0: 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69  ific data */.  i
eac0: 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
ead0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
eae0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c  char *zName, sql
eaf0: 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20  ite3_file*,.    
eb00: 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66             int f
eb10: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46  lags, int *pOutF
eb20: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
eb30: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
eb40: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
eb50: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e   *zName, int syn
eb60: 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  cDir);.  int (*x
eb70: 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f  Access)(sqlite3_
eb80: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
eb90: 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61   *zName, int fla
eba0: 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  gs, int *pResOut
ebb0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c  );.  int (*xFull
ebc0: 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65  Pathname)(sqlite
ebd0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
ebe0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e  ar *zName, int n
ebf0: 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  Out, char *zOut)
ec00: 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f  ;.  void *(*xDlO
ec10: 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
ec20: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
ec30: 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69  Filename);.  voi
ec40: 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71  d (*xDlError)(sq
ec50: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
ec60: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72  nByte, char *zEr
ec70: 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a  rMsg);.  void (*
ec80: 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65  (*xDlSym)(sqlite
ec90: 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f  3_vfs*,void*, co
eca0: 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f  nst char *zSymbo
ecb0: 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69  l))(void);.  voi
ecc0: 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71  d (*xDlClose)(sq
ecd0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64  lite3_vfs*, void
ece0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e  *);.  int (*xRan
ecf0: 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33  domness)(sqlite3
ed00: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
ed10: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
ed20: 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73   int (*xSleep)(s
ed30: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
ed40: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a   microseconds);.
ed50: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
ed60: 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  Time)(sqlite3_vf
ed70: 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20  s*, double*);.  
ed80: 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72  int (*xGetLastEr
ed90: 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ror)(sqlite3_vfs
eda0: 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b  *, int, char *);
edb0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
edc0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
edd0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66   in version 1 of
ede0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
edf0: 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69  object.  ** defi
ee00: 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74  nition.  Those t
ee10: 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61  hat follow are a
ee20: 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20  dded in version 
ee30: 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a  2 or later.  */.
ee40: 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74    int (*xCurrent
ee50: 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74  TimeInt64)(sqlit
ee60: 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33  e3_vfs*, sqlite3
ee70: 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20  _int64*);.  /*. 
ee80: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
ee90: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
eea0: 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66  sions 1 and 2 of
eeb0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
eec0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f  object..  ** Tho
eed0: 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72  se below are for
eee0: 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67   version 3 and g
eef0: 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69  reater..  */.  i
ef00: 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43  nt (*xSetSystemC
ef10: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
ef20: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
ef30: 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79  Name, sqlite3_sy
ef40: 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71  scall_ptr);.  sq
ef50: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
ef60: 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61  r (*xGetSystemCa
ef70: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
ef80: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
ef90: 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68  ame);.  const ch
efa0: 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65  ar *(*xNextSyste
efb0: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
efc0: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
efd0: 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20  *zName);.  /*.  
efe0: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
eff0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
f000: 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33  ions 1 through 3
f010: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
f020: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
f030: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
f040: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 75  e appended in fu
f050: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  ture versions.  
f060: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
f070: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
f080: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
f090: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20  this happens. . 
f0a0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
f0b0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
f0c0: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
f0d0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
f0e0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
f0f0: 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
f100: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
f110: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
f120: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
f130: 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
f140: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
f150: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
f160: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
f170: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
f180: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
f190: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a   looking for..**
f1a0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
f1b0: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
f1c0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
f1d0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
f1e0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
f1f0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68   exists..** With
f200: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
f210: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
f220: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
f230: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
f240: 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f  he named directo
f250: 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  ry is both reada
f260: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
f270: 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f  .** (in other wo
f280: 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61  rds, if files ca
f290: 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f  n be added, remo
f2a0: 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64  ved, and renamed
f2b0: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64   within.** the d
f2c0: 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68  irectory)..** Th
f2d0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
f2e0: 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61  READWRITE consta
f2f0: 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  nt is currently 
f300: 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65  used only by the
f310: 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  .** [temp_store_
f320: 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
f330: 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63  ], though this c
f340: 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61  ould change in a
f350: 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
f360: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
f370: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
f380: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
f390: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
f3a0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
f3b0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
f3c0: 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
f3d0: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e  _ACCESS_READ con
f3e0: 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72  stant is.** curr
f3f0: 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68  ently unused, th
f400: 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65  ough it might be
f410: 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72   used in a futur
f420: 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
f430: 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
f440: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
f450: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
f460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
f470: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20  SS_READWRITE 1  
f480: 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47   /* Used by PRAG
f490: 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  MA temp_store_di
f4a0: 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69  rectory */.#defi
f4b0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
f4c0: 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f  _READ      2   /
f4d0: 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  * Unused */../*.
f4e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
f4f0: 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c  gs for the xShmL
f500: 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ock VFS method.*
f510: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
f520: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  er constants def
f530: 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20  ine the various 
f540: 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f  locking operatio
f550: 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79  ns.** allowed by
f560: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   the xShmLock me
f570: 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  thod of [sqlite3
f580: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54  _io_methods].  T
f590: 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
f5a0: 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67  are the only leg
f5b0: 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  al combinations 
f5c0: 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a  of flags to the.
f5d0: 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  ** xShmLock meth
f5e0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
f5f0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f600: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
f610: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
f620: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
f630: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
f640: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
f650: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
f660: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
f670: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
f680: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
f690: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
f6a0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
f6b0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  </ul>.**.** When
f6c0: 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20   unlocking, the 
f6d0: 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45  same SHARED or E
f6e0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75  XCLUSIVE flag mu
f6f0: 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61  st be supplied a
f700: 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6f  s.** was given o
f710: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
f720: 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a  ing lock.  .**.*
f730: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
f740: 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69  ethod can transi
f750: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c  tion between unl
f760: 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44  ocked and SHARED
f770: 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75   or.** between u
f780: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c  nlocked and EXCL
f790: 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f  USIVE.  It canno
f7a0: 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  t transition bet
f7b0: 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61  ween SHARED.** a
f7c0: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f  nd EXCLUSIVE..*/
f7d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f7e0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  SHM_UNLOCK      
f7f0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
f800: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20  E_SHM_LOCK      
f810: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
f820: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20  ITE_SHM_SHARED  
f830: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
f840: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
f850: 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20  IVE    8../*.** 
f860: 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75  CAPI3REF: Maximu
f870: 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78  m xShmLock index
f880: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
f890: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73  ock method on [s
f8a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
f8b0: 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65  s] may use value
f8c0: 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61  s.** between 0 a
f8d0: 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f  nd this upper bo
f8e0: 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73  und as its "offs
f8f0: 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  et" argument..**
f900: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
f910: 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65   will never atte
f920: 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f  mpt to acquire o
f930: 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c  r release a.** l
f940: 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74  ock outside of t
f950: 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65  his range.*/.#de
f960: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f970: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a  NLOCK        8..
f980: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f990: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
f9a0: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
f9b0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
f9c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
f9d0: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
f9e0: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
f9f0: 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
fa00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fa10: 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
fa20: 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
fa30: 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
fa40: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
fa50: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fa60: 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
fa70: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
fa80: 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
fa90: 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
faa0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
fab0: 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
fac0: 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
fad0: 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
fae0: 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
faf0: 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
fb00: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
fb10: 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
fb20: 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
fb30: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
fb40: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fb50: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
fb60: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
fb70: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
fb80: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
fb90: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
fba0: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
fbb0: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
fbc0: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
fbd0: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
fbe0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
fbf0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
fc00: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
fc10: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
fc20: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
fc30: 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
fc40: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
fc50: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fc60: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
fc70: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
fc80: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
fc90: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
fca0: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
fcb0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
fcc0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
fcd0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
fce0: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
fcf0: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
fd00: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
fd10: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
fd20: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
fd30: 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
fd40: 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
fd50: 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
fd60: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
fd70: 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
fd80: 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
fd90: 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
fda0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
fdb0: 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
fdc0: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
fdd0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
fde0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
fdf0: 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
fe00: 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
fe10: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
fe20: 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
fe30: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
fe40: 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
fe50: 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
fe60: 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
fe70: 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
fe80: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
fe90: 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
fea0: 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
feb0: 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
fec0: 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
fed0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
fee0: 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
fef0: 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
ff00: 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
ff10: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
ff20: 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
ff30: 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
ff40: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
ff50: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
ff60: 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
ff70: 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
ff80: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
ff90: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
ffa0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
ffb0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
ffc0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
ffd0: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
ffe0: 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
fff0: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
10000 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
10010 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
10020 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
10030 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
10040 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
10050 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
10060 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
10070 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
10080 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
10090 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
100a0 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
100b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
100c0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
100d0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
100e0 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
100f0 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
10100 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
10110 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
10120 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
10130 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
10140 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
10150 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
10160 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
10170 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
10180 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
10190 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
101a0 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
101b0 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
101c0 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
101d0 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
101e0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
101f0 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
10200 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
10210 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
10220 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
10230 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
10240 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
10250 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
10260 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
10270 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
10280 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
10290 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
102a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
102b0 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
102c0 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
102d0 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
102e0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
102f0 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
10300 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
10310 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
10320 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
10330 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
10340 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
10350 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
10360 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
10370 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
10380 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10390 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
103a0 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
103b0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
103c0 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
103d0 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
103e0 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
103f0 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
10400 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
10410 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
10420 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
10430 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
10440 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
10450 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
10460 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
10470 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
10480 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
10490 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
104a0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
104b0 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
104c0 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
104d0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
104e0 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
104f0 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
10500 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
10510 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
10520 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
10530 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
10540 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10550 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
10560 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
10570 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
10580 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
10590 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
105a0 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
105b0 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
105c0 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
105d0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
105e0 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
105f0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
10600 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
10610 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
10620 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
10630 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
10640 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
10650 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
10660 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
10670 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
10680 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
10690 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
106a0 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
106b0 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
106c0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
106d0 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
106e0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
106f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
10700 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
10710 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
10720 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
10730 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
10740 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
10750 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
10760 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
10770 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
10780 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
10790 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
107a0 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
107b0 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
107c0 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
107d0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
107e0 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
107f0 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
10800 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
10810 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
10820 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
10830 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
10840 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
10850 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
10860 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
10870 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
10880 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
10890 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
108a0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
108b0 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
108c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
108d0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
108e0 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
108f0 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
10900 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
10910 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
10920 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
10930 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
10940 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
10950 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
10960 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
10970 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
10980 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
10990 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
109a0 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
109b0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
109c0 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
109d0 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
109e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
109f0 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
10a00 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
10a10 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
10a20 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
10a30 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
10a40 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
10a50 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10a60 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
10a70 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
10a80 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
10a90 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
10aa0 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
10ab0 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
10ac0 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
10ad0 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
10ae0 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
10af0 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
10b00 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
10b10 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
10b20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
10b30 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
10b40 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
10b50 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
10b60 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
10b70 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
10b80 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
10b90 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
10ba0 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69  *.** <b>The sqli
10bb0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
10bc0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
10bd0 72 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 70  readsafe. The ap
10be0 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
10bf0 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t ensure that no
10c00 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
10c10 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
10c20 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
10c30 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
10c40 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10c50 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a  is running.</b>.
10c60 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10c70 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
10c80 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  face.** may only
10c90 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
10ca0 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
10cb0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
10cc0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
10cd0 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
10ce0 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
10cf0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10d00 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
10d10 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10d20 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
10d30 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10d40 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
10d50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
10d60 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
10d70 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
10d80 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
10d90 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
10da0 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
10db0 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
10dc0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
10dd0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
10de0 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
10df0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
10e00 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10e10 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
10e20 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
10e30 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10e40 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
10e50 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
10e60 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
10e70 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
10e80 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
10e90 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
10ea0 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
10eb0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
10ec0 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
10ed0 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
10ee0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
10ef0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10f00 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
10f10 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
10f20 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
10f30 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
10f40 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
10f50 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
10f60 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
10f70 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
10f80 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
10f90 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
10fa0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
10fb0 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
10fc0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
10fd0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10fe0 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
10ff0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
11000 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
11010 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11020 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
11030 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
11040 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
11050 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
11060 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f   used to make co
11070 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
11080 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74  hanges to a [dat
11090 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
110a0 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  ].  The interfac
110b0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a  e is similar to.
110c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
110d0 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  ig()] except tha
110e0 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70  t the changes ap
110f0 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a  ply to a single.
11100 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11110 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66  nection] (specif
11120 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
11130 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a   argument)..**.*
11140 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
11150 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
11160 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e  _db_config(D,V,.
11170 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b  ..)  is the.** [
11180 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
11190 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66  LOOKASIDE | conf
111a0 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20  iguration verb] 
111b0 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
111c0 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63  e .** that indic
111d0 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74  ates what aspect
111e0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
111f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
11200 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
11210 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74  d..** Subsequent
11220 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20   arguments vary 
11230 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
11240 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
11250 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  erb..**.** ^Call
11260 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  s to sqlite3_db_
11270 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20  config() return 
11280 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64  SQLITE_OK if and
11290 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20   only if.** the 
112a0 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72  call is consider
112b0 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a  ed successful..*
112c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  /.int sqlite3_db
112d0 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
112e0 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
112f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11300 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
11310 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
11320 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
11330 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
11340 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
11350 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
11360 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
11370 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
11380 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
11390 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
113a0 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
113b0 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
113c0 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
113d0 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
113e0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
113f0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
11400 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
11410 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
11420 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
11430 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11440 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
11450 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
11460 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
11470 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
11480 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
11490 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
114a0 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
114b0 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
114c0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
114d0 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
114e0 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
114f0 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
11500 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
11510 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
11520 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
11530 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11540 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
11550 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
11560 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
11570 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
11580 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
11590 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
115a0 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
115b0 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
115c0 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
115d0 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
115e0 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
115f0 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
11600 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
11610 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
11620 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
11630 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
11640 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
11650 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
11660 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
11670 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
11680 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
11690 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
116a0 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
116b0 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
116c0 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
116d0 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
116e0 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
116f0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
11700 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
11710 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
11720 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
11730 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
11740 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
11750 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
11760 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
11770 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
11780 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
11790 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
117a0 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
117b0 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
117c0 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
117d0 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
117e0 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
117f0 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
11800 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
11810 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
11820 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
11830 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11840 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
11850 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
11860 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
11870 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
11880 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
11890 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
118a0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
118b0 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
118c0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
118d0 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
118e0 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
118f0 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
11900 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
11910 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
11920 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
11930 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
11940 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
11950 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
11960 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
11970 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
11980 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
11990 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
119a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
119b0 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
119c0 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
119d0 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
119e0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
119f0 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
11a00 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
11a10 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
11a20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
11a30 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
11a40 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
11a50 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
11a60 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
11a70 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
11a80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11a90 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
11aa0 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
11ab0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
11ac0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
11ad0 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
11ae0 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
11af0 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
11b00 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
11b10 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
11b20 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
11b30 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
11b40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
11b50 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
11b60 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
11b70 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20  allocator.  For 
11b80 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
11b90 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
11ba0 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
11bb0 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
11bc0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
11bd0 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
11be0 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
11bf0 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
11c00 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
11c10 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
11c20 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
11c30 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
11c40 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
11c50 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
11c60 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
11c70 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
11c80 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
11c90 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
11ca0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
11cb0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
11cc0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
11cd0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
11ce0 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
11cf0 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
11d00 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
11d10 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
11d20 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
11d30 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
11d40 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
11d50 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
11d60 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
11d70 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
11d80 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
11d90 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
11da0 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
11db0 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
11dc0 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
11dd0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
11de0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
11df0 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
11e00 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
11e10 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11e20 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
11e30 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
11e40 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
11e50 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
11e60 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
11e70 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
11e80 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
11e90 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
11ea0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
11eb0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
11ec0 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
11ed0 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
11ee0 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
11ef0 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
11f00 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
11f10 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
11f20 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
11f30 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
11f40 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
11f50 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
11f60 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
11f70 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
11f80 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
11f90 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
11fa0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
11fb0 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
11fc0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
11fd0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
11fe0 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
11ff0 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
12000 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
12010 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
12020 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
12030 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
12040 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
12050 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
12060 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12070 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
12080 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
12090 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
120a0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
120b0 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
120c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
120d0 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
120e0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
120f0 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
12100 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
12110 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
12120 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
12130 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
12140 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
12150 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
12160 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
12170 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
12180 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
12190 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
121a0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
121b0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
121c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
121d0 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
121e0 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
121f0 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
12200 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
12210 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
12220 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12230 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
12240 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
12250 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
12260 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
12270 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
12280 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
12290 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
122a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
122b0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
122c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
122d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
122e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
122f0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
12300 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
12310 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12320 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
12330 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
12340 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
12350 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
12360 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
12370 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
12380 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
12390 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
123a0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
123b0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
123c0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
123d0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
123e0 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
123f0 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
12400 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
12410 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
12420 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
12430 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
12440 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
12450 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
12460 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12470 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
12480 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
12490 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
124a0 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
124b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
124c0 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
124d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
124e0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
124f0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
12500 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
12510 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
12520 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
12530 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
12540 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
12550 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
12560 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
12570 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
12580 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
12590 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
125a0 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
125b0 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
125c0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
125d0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
125e0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
125f0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12600 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
12610 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
12620 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
12630 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
12640 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
12650 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
12660 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
12670 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
12680 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
12690 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
126a0 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
126b0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
126c0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
126d0 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
126e0 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
126f0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
12700 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12710 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
12720 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
12730 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
12740 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
12750 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
12760 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
12770 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
12780 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
12790 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
127a0 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
127b0 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
127c0 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
127d0 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
127e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
127f0 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
12800 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
12810 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
12820 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
12830 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
12840 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
12850 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
12860 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
12870 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
12880 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
12890 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
128a0 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
128b0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
128c0 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
128d0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
128e0 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
128f0 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
12900 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
12910 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
12920 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
12930 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
12940 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
12950 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12960 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12970 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12980 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12990 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
129a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
129b0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
129c0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
129d0 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
129e0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
129f0 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
12a00 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12a10 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
12a20 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
12a30 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
12a40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12a50 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
12a60 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
12a70 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12a80 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
12a90 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
12aa0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
12ab0 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
12ac0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
12ad0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
12ae0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
12af0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
12b00 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12b10 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
12b20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12b30 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
12b40 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
12b50 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
12b60 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
12b70 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
12b80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12b90 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
12ba0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
12bb0 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
12bc0 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
12bd0 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
12be0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12bf0 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
12c00 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
12c10 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
12c20 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
12c30 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
12c40 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
12c50 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
12c60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12c70 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
12c80 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
12c90 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
12ca0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
12cb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
12cc0 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
12cd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12ce0 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
12cf0 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
12d00 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
12d10 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12d20 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12d30 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12d40 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12d50 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12d60 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12d70 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
12d80 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
12d90 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
12da0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12db0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
12dc0 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
12dd0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
12de0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
12df0 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
12e00 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
12e10 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
12e20 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
12e30 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12e40 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
12e50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12e60 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
12e70 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
12e80 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f  _CONFIG_MALLOC o
12e90 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12ea0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12eb0 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
12ec0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
12ed0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
12ee0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12ef0 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
12f00 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
12f10 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
12f20 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
12f30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12f40 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
12f50 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
12f60 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
12f70 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
12f80 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
12f90 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
12fa0 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
12fb0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
12fc0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
12fd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
12fe0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
12ff0 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
13000 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
13010 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
13020 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
13030 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13040 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
13050 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13060 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
13070 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
13080 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
13090 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
130a0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
130b0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
130c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
130d0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
130e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
130f0 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
13100 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
13110 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
13120 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
13130 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
13140 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
13150 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
13160 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
13170 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
13180 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
13190 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
131a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
131b0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
131c0 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
131d0 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
131e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
131f0 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
13200 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
13210 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
13220 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13230 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
13240 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
13250 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
13260 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
13270 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13280 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f  _MEMSTATUS optio
13290 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
132a0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
132b0 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65  int,.** interpre
132c0 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
132d0 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
132e0 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
132f0 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a  collection of.**
13300 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13310 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  on statistics. ^
13320 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
13330 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
13340 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  cs are.** disabl
13350 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ed, the followin
13360 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
13370 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
13380 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
13390 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
133a0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
133b0 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
133c0 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
133d0 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
133e0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
133f0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
13400 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
13410 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
13420 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  64()].**   </ul>
13430 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
13440 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
13450 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
13460 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
13470 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
13480 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
13490 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
134a0 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
134b0 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
134c0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
134d0 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
134e0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
134f0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
13500 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13510 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
13520 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
13530 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
13540 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
13550 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69  FIG_SCRATCH opti
13560 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
13570 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
13580 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  fer.** that SQLi
13590 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73  te can use for s
135a0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
135b0 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65  ^(There are thre
135c0 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74  e arguments.** t
135d0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
135e0 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e  SCRATCH:  A poin
135f0 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
13600 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
13610 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
13620 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
13630 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
13640 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
13650 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
13660 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
13670 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
13680 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
13690 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
136a0 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a  ations (N).)^.**
136b0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
136c0 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
136d0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
136e0 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
136f0 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
13700 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
13710 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
13720 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d  e will not use m
13730 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
13740 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
13750 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c   thread..** ^SQL
13760 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72  ite will never r
13770 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68  equest a scratch
13780 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
13790 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74  more than 6.** t
137a0 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
137b0 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20  e page size..** 
137c0 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
137d0 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
137e0 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
137f0 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
13800 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
13810 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
13820 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
13830 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
13840 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
13850 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
13860 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
13870 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  p>.** ^When the 
13880 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76  application prov
13890 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20  ides any amount 
138a0 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  of scratch memor
138b0 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54  y using.** SQLIT
138c0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
138d0 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20  , SQLite avoids 
138e0 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67  unnecessary larg
138f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
13900 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61  lloc|heap alloca
13910 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20  tions]..** This 
13920 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e  can help [Robson
13930 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d   proof|prevent m
13940 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13950 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74   failures] due t
13960 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65  o heap.** fragme
13970 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d  ntation in low-m
13980 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73  emory embedded s
13990 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  ystems..** </dd>
139a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
139b0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
139c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
139d0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
139e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
139f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
13a00 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20  AGECACHE option 
13a10 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f  specifies a memo
13a20 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20  ry pool.** that 
13a30 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
13a40 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
13a50 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
13a60 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
13a70 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
13a80 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  entation.  .** T
13a90 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
13aa0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f  n option is a no
13ab0 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63  -op if an applic
13ac0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
13ad0 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
13ae0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
13af0 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53  ded using the [S
13b00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13b10 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65  CHE2]..** ^There
13b20 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
13b30 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43  ents to SQLITE_C
13b40 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a  ONFIG_PAGECACHE:
13b50 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   A pointer to.**
13b60 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
13b70 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74  memory (pMem), t
13b80 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
13b90 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20  page cache line 
13ba0 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
13bb0 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65   number of cache
13bc0 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54   lines (N)..** T
13bd0 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73  he sz argument s
13be0 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a  hould be the siz
13bf0 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  e of the largest
13c00 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a   database page.*
13c10 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77  * (a power of tw
13c20 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e  o between 512 an
13c30 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f  d 65536) plus so
13c40 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20 66  me extra bytes f
13c50 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
13c60 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75  header.  ^The nu
13c70 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 79  mber of extra by
13c80 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 68  tes needed by th
13c90 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a  e page header.**
13ca0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
13cb0 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45  ed using [SQLITE
13cc0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
13cd0 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73  DRSZ]..** ^It is
13ce0 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
13cf0 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
13d00 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20   memory,.** for 
13d10 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72  the sz parameter
13d20 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68   to be larger th
13d30 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54  an necessary.  T
13d40 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d  he pMem.** argum
13d50 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74 68  ent must be eith
13d60 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
13d70 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  r or a pointer t
13d80 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  o an 8-byte.** a
13d90 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20  ligned block of 
13da0 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61  memory of at lea
13db0 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f  st sz*N bytes, o
13dc0 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73  therwise.** subs
13dd0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
13de0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
13df0 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e   ^When pMem is n
13e00 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20  ot NULL, SQLite 
13e10 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75  will strive to u
13e20 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
13e30 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74  ovided.** to sat
13e40 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65 20  isfy page cache 
13e50 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62  needs, falling b
13e60 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ack to [sqlite3_
13e70 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20  malloc()] if.** 
13e80 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e  a page cache lin
13e90 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e  e is larger than
13ea0 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20   sz bytes or if 
13eb0 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20  all of the pMem 
13ec0 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68  buffer.** is exh
13ed0 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70  austed..** ^If p
13ee0 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20  Mem is NULL and 
13ef0 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  N is non-zero, t
13f00 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61 73  hen each databas
13f10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
13f20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20  does an initial 
13f30 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  bulk allocation 
13f40 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
13f50 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73  emory.** from [s
13f60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
13f70 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20   sufficient for 
13f80 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66  N cache lines if
13f90 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f   N is positive o
13fa0 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20  r.** of -1024*N 
13fb0 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65  bytes if N is ne
13fc0 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64  gative, . ^If ad
13fd0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
13fe0 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
13ff0 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
14000 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
14010 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a  by the initial.*
14020 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  * allocation, th
14030 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  en SQLite goes t
14040 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
14050 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20  c()] separately 
14060 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69  for each.** addi
14070 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e  tional cache lin
14080 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
14090 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
140a0 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAP]] <dt>SQLITE
140b0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74  _CONFIG_HEAP</dt
140c0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
140d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
140e0 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  P option specifi
140f0 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
14100 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68  ry buffer .** th
14110 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
14120 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
14130 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
14140 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
14150 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73  s.** beyond thos
14160 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62  e provided for b
14170 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
14180 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a  _SCRATCH] and.**
14190 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
141a0 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e  PAGECACHE]..** ^
141b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
141c0 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73  G_HEAP option is
141d0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
141e0 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
141f0 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69  piled.** with ei
14200 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
14210 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20  BLE_MEMSYS3] or 
14220 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
14230 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75  EMSYS5] and retu
14240 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rns.** [SQLITE_E
14250 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64  RROR] if invoked
14260 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e   otherwise..** ^
14270 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
14280 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
14290 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a  ITE_CONFIG_HEAP:
142a0 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c  .** An 8-byte al
142b0 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f  igned pointer to
142c0 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20   the memory,.** 
142d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
142e0 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72  tes in the memor
142f0 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68  y buffer, and th
14300 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
14310 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  tion size..** ^I
14320 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e  f the first poin
14330 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
14340 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c  pointer) is NULL
14350 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65  , then SQLite re
14360 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e  verts.** to usin
14370 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65  g its default me
14380 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28  mory allocator (
14390 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
143a0 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  c() implementati
143b0 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20  on),.** undoing 
143c0 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61  any prior invoca
143d0 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f  tion of [SQLITE_
143e0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20  CONFIG_MALLOC]. 
143f0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f   ^If the.** memo
14400 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  ry pointer is no
14410 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20  t NULL then the 
14420 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
14430 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
14440 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
14450 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
14460 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
14470 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
14480 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
14490 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
144a0 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
144b0 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
144c0 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
144d0 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
144e0 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
144f0 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
14500 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d  ed..** The minim
14510 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
14520 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20  ze is capped at 
14530 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c  2**12. Reasonabl
14540 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20  e values.** for 
14550 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
14560 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20  cation size are 
14570 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a  2**5 through 2**
14580 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  8.</dd>.**.** [[
14590 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
145a0 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
145b0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
145c0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
145d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
145e0 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65  UTEX option take
145f0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14600 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a  ent which is a.*
14610 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
14620 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
14630 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
14640 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
14650 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
14660 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c 74  nt specifies alt
14670 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
14680 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
14690 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20  s to be used.** 
146a0 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74  in place the mut
146b0 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
146c0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
146d0 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
146e0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
146f0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
14700 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
14710 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
14720 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
14730 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
14740 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
14750 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
14760 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
14770 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
14780 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
14790 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
147a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
147b0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
147c0 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
147d0 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
147e0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
147f0 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
14800 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
14810 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
14820 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
14830 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
14840 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
14850 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
14860 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
14870 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14880 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
14890 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
148a0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
148b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
148c0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
148d0 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e  _GETMUTEX option
148e0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
148f0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
14900 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
14910 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
14920 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
14930 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
14940 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
14950 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
14960 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
14970 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
14980 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
14990 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
149a0 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
149b0 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
149c0 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
149d0 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
149e0 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
149f0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
14a00 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
14a10 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
14a20 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
14a30 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
14a40 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
14a50 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
14a60 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14a70 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
14a80 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
14a90 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
14aa0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
14ab0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
14ac0 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
14ad0 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
14ae0 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
14af0 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
14b00 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
14b10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
14b20 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
14b30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14b40 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
14b50 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
14b60 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
14b70 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
14b80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14b90 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
14ba0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14bb0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
14bc0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14bd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
14be0 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20  OOKASIDE option 
14bf0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
14c00 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
14c10 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  ne.** the defaul
14c20 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73  t size of lookas
14c30 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61  ide memory on ea
14c40 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ch [database con
14c50 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65  nection]..** The
14c60 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
14c70 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
14c80 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
14c90 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
14ca0 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
14cb0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
14cc0 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
14cd0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
14ce0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
14cf0 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ^(SQLITE_CONFIG_
14d00 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74  LOOKASIDE.** set
14d10 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74  s the <i>default
14d20 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73  </i> lookaside s
14d30 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45  ize. The [SQLITE
14d40 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
14d50 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74  IDE].** option t
14d60 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
14d70 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75  nfig()] can be u
14d80 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
14d90 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63  e lookaside.** c
14da0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20  onfiguration on 
14db0 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65  individual conne
14dc0 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a  ctions.)^ </dd>.
14dd0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14de0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20  ONFIG_PCACHE2]] 
14df0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14e00 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  G_PCACHE2</dt>.*
14e10 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14e20 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
14e30 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  E2 option takes 
14e40 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
14e50 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
14e60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
14e70 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
14e80 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
14e90 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
14ea0 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69  ecifies.** the i
14eb0 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63 75  nterface to a cu
14ec0 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
14ed0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
14ee0 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b  ^.** ^SQLite mak
14ef0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
14f00 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
14f10 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
14f20 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  t.</dd>.**.** [[
14f30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14f40 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
14f50 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14f60 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
14f70 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14f80 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
14f90 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
14fa0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14fb0 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
14fc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b   pointer to an [
14fd0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
14fe0 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
14ff0 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
15000 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e  of.** the curren
15010 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
15020 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
15030 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
15040 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15050 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
15060 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15070 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
15080 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
15090 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
150a0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  n is used to con
150b0 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74  figure the SQLit
150c0 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72  e.** global [err
150d0 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68  or log]..** (^Th
150e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
150f0 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
15100 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
15110 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
15120 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
15130 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
15140 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
15150 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
15160 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
15170 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
15180 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
15190 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
151a0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
151b0 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
151c0 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
151d0 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
151e0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
151f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
15200 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
15210 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
15220 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
15230 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
15240 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
15250 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
15260 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
15270 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15280 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
15290 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
152a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
152b0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
152c0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
152d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
152e0 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
152f0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
15300 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
15310 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
15320 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
15330 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
15340 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15350 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
15360 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
15370 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
15380 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
15390 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
153a0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
153b0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
153c0 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
153d0 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
153e0 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
153f0 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
15400 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
15410 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
15420 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
15430 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
15440 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
15450 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
15460 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
15470 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
15480 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
15490 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
154a0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
154b0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
154c0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
154d0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
154e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
154f0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
15500 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
15510 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
15520 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15530 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
15540 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15550 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65  URI.** <dd>^(The
15560 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
15570 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  RI option takes 
15580 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
15590 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a  t of type int..*
155a0 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  * If non-zero, t
155b0 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
155c0 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
155d0 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
155e0 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a  ameter is zero,.
155f0 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  ** then URI hand
15600 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
15610 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66   disabled.)^ ^If
15620 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
15630 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61   globally.** ena
15640 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61  bled, all filena
15650 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73  mes passed to [s
15660 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
15670 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
15680 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
15690 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a  _open16()] or.**
156a0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61   specified as pa
156b0 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63  rt of [ATTACH] c
156c0 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65  ommands are inte
156d0 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c  rpreted as URIs,
156e0 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f   regardless.** o
156f0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
15700 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
15710 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73  N_URI] flag is s
15720 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  et when the data
15730 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
15740 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49  on is opened. ^I
15750 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
15760 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
15770 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
15780 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
15790 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
157a0 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
157b0 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
157c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
157d0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
157e0 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c  d. ^(By default,
157f0 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
15800 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73   globally.** dis
15810 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75  abled. The defau
15820 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20  lt value may be 
15830 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69  changed by compi
15840 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a  ling with the.**
15850 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
15860 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  ] symbol defined
15870 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
15880 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
15890 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20  NG_INDEX_SCAN]] 
158a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
158b0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
158c0 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68  _SCAN.** <dd>^Th
158d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
158e0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
158f0 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  CAN option takes
15900 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
15910 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68  r.** argument wh
15920 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74  ich is interpret
15930 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20  ed as a boolean 
15940 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
15950 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a  le or disable.**
15960 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65   the use of cove
15970 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72  ring indices for
15980 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
15990 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
159a0 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68  ptimizer..** ^Th
159b0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
159c0 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
159d0 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
159e0 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
159f0 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
15a00 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15a10 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
15a20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
15a30 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
15a40 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
15a50 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
15a60 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
15a70 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
15a80 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
15a90 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
15aa0 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
15ab0 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
15ac0 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
15ad0 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
15ae0 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69   when the optimi
15af0 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  zation is enable
15b00 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68  d.  Providing th
15b10 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20  e ability to.** 
15b20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69  disable the opti
15b30 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  mization allows 
15b40 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79  the older, buggy
15b50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
15b60 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
15b70 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e  hout change even
15b80 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73   with newer vers
15b90 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
15ba0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15bb0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b  ONFIG_PCACHE]] [
15bc0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
15bd0 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64  ETPCACHE]].** <d
15be0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15bf0 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54  PCACHE and SQLIT
15c00 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15c10 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65  HE.** <dd> These
15c20 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73   options are obs
15c30 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64  olete and should
15c40 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
15c50 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65  new code..** The
15c60 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  y are retained f
15c70 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
15c80 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61  patibility but a
15c90 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a  re now no-ops..*
15ca0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
15cb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
15cc0 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  LLOG]].** <dt>SQ
15cd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15ce0 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  OG.** <dd>This o
15cf0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
15d00 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74  ailable if sqlit
15d10 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
15d20 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
15d30 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d  E_ENABLE_SQLLOG]
15d40 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
15d50 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68  acro defined. Th
15d60 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
15d70 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20   should.** be a 
15d80 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
15d90 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f  ction of type vo
15da0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
15db0 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  te3*,const char*
15dc0 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73  , int)..** The s
15dd0 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  econd should be 
15de0 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e  of type (void*).
15df0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
15e00 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20   invoked by the 
15e10 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68  library.** in th
15e20 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72  ree separate cir
15e30 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e  cumstances, iden
15e40 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61  tified by the va
15e50 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
15e60 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
15e70 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f  meter. If the fo
15e80 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
15e90 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61  s 0, then the da
15ea0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15eb0 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  n.** passed as t
15ec0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
15ed0 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  nt has just been
15ee0 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69   opened. The thi
15ef0 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70  rd argument.** p
15f00 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
15f10 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  r containing the
15f20 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69   name of the mai
15f30 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
15f40 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
15f50 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31  h parameter is 1
15f60 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73  , then the SQL s
15f70 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68  tatement that th
15f80 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
15f90 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68  r.** points to h
15fa0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65  as just been exe
15fb0 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68  cuted. Or, if th
15fc0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
15fd0 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a  er is 2, then.**
15fe0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
15ff0 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20  being passed as 
16000 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
16010 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c  eter is being cl
16020 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69  osed. The.** thi
16030 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
16040 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74  passed NULL In t
16050 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78  his case.  An ex
16060 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74  ample of using t
16070 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  his.** configura
16080 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20  tion option can 
16090 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22  be seen in the "
160a0 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73  test_sqllog.c" s
160b0 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a  ource file in.**
160c0 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53   the canonical S
160d0 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65  QLite source tre
160e0 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  e.</dd>.**.** [[
160f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
16100 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  AP_SIZE]].** <dt
16110 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
16120 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  MAP_SIZE.** <dd>
16130 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  ^SQLITE_CONFIG_M
16140 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74  MAP_SIZE takes t
16150 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  wo 64-bit intege
16160 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  r (sqlite3_int64
16170 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  ) values.** that
16180 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74   are the default
16190 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
161a0 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65   (the default se
161b0 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52  tting for.** [PR
161c0 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29  AGMA mmap_size])
161d0 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
161e0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
161f0 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68  ze limit..** ^Th
16200 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
16210 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  g can be overrid
16220 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61  den by each data
16230 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16240 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20  using.** either 
16250 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  the [PRAGMA mmap
16260 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20  _size] command, 
16270 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a  or by using the.
16280 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
16290 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
162a0 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65   control.  ^(The
162b0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
162c0 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69   mmap size.** wi
162d0 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74  ll be silently t
162e0 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65  runcated if nece
162f0 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69 74  ssary so that it
16300 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64   does not exceed
16310 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d   the.** compile-
16320 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61  time maximum mma
16330 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74 68  p size set by th
16340 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58  e.** [SQLITE_MAX
16350 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70  _MMAP_SIZE] comp
16360 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
16370 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72  )^.** ^If either
16380 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
16390 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61  s option is nega
163a0 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20  tive, then that 
163b0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63  argument is.** c
163c0 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f  hanged to its co
163d0 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75  mpile-time defau
163e0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  lt..**.** [[SQLI
163f0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
16400 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  HEAPSIZE]].** <d
16410 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16420 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a  WIN32_HEAPSIZE.*
16430 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
16440 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
16450 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69  EAPSIZE option i
16460 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
16470 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a   if SQLite is.**
16480 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69   compiled for Wi
16490 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b  ndows with the [
164a0 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c  SQLITE_WIN32_MAL
164b0 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOC] pre-process
164c0 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69  or macro.** defi
164d0 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e  ned. ^SQLITE_CON
164e0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
164f0 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69  ZE takes a 32-bi
16500 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67  t unsigned integ
16510 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74  er value.** that
16520 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 6d   specifies the m
16530 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74  aximum size of t
16540 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70 2e  he created heap.
16550 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16560 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
16570 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  RSZ]].** <dt>SQL
16580 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16590 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  E_HDRSZ.** <dd>^
165a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
165b0 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f  G_PCACHE_HDRSZ o
165c0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
165d0 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
165e0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
165f0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
16600 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  er and writes in
16610 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20  to that integer 
16620 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
16630 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72  tra.** bytes per
16640 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20 66   page required f
16650 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e 20  or each page in 
16660 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
16670 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
16680 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72  e amount of extr
16690 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64  a space required
166a0 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65   can change depe
166b0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d  nding on the com
166c0 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74  piler,.** target
166d0 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53   platform, and S
166e0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a  QLite version..*
166f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16700 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20  NFIG_PMASZ]].** 
16710 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16720 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e  G_PMASZ.** <dd>^
16730 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16740 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74  G_PMASZ option t
16750 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61  akes a single pa
16760 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
16770 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
16780 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74 73  integer and sets
16790 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d   the "Minimum PM
167a0 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20  A Size" for the 
167b0 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a  multithreaded.**
167c0 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20   sorter to that 
167d0 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64 65  integer.  The de
167e0 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d  fault minimum PM
167f0 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62 79  A Size is set by
16800 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
16810 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f  SORTER_PMASZ] co
16820 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16830 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73 20  n.  New threads 
16840 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20  are launched.** 
16850 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72  to help with sor
16860 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65  t operations whe
16870 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  n multithreaded 
16880 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e  sorting.** is en
16890 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65  abled (using the
168a0 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64 73   [PRAGMA threads
168b0 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74  ] command) and t
168c0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e  he amount of con
168d0 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f  tent.** to be so
168e0 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68 65  rted exceeds the
168f0 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73   page size times
16900 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20   the minimum of 
16910 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63  the.** [PRAGMA c
16920 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69  ache_size] setti
16930 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75  ng and this valu
16940 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  e..**.** [[SQLIT
16950 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
16960 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74  L_SPILL]].** <dt
16970 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
16980 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a  TMTJRNL_SPILL.**
16990 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
169a0 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c  _CONFIG_STMTJRNL
169b0 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61  _SPILL option ta
169c0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
169d0 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
169e0 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61  becomes the [sta
169f0 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20  tement journal] 
16a00 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68  spill-to-disk th
16a10 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53  reshold.  .** [S
16a20 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
16a30 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d  s] are held in m
16a40 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69  emory until thei
16a50 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73  r size (in bytes
16a60 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69  ).** exceeds thi
16a70 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20  s threshold, at 
16a80 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79  which point they
16a90 20 61 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20   are written to 
16aa0 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74  disk..** Or if t
16ab0 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20  he threshold is 
16ac0 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f  -1, statement jo
16ad0 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79  urnals are alway
16ae0 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73  s held.** exclus
16af0 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e  ively in memory.
16b00 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73  .** Since many s
16b10 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c  tatement journal
16b20 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c  s never become l
16b30 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68  arge, setting th
16b40 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73  e spill.** thres
16b50 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20  hold to a value 
16b60 73 75 63 68 20 61 73 20 36 34 4b 69 42 20 63 61  such as 64KiB ca
16b70 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75 63 65  n greatly reduce
16b80 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a   the amount of.*
16b90 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74  * I/O required t
16ba0 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d  o support statem
16bb0 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  ent rollback..**
16bc0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
16bd0 75 65 20 66 6f 72 20 74 68 69 73 20 73 65 74 74  ue for this sett
16be0 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65  ing is controlle
16bf0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  d by the.** [SQL
16c00 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  ITE_STMTJRNL_SPI
16c10 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  LL] compile-time
16c20 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c   option..** </dl
16c30 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
16c40 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
16c50 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
16c60 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
16c70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
16c80 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
16c90 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
16ca0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
16cb0 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
16cc0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
16cd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
16ce0 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
16cf0 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
16d00 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
16d10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16d20 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
16d30 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
16d40 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
16d50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16d60 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
16d70 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
16d80 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
16d90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16da0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
16db0 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
16dc0 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
16dd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16de0 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
16df0 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
16e00 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
16e10 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
16e20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
16e30 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
16e40 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
16e50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16e60 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
16e70 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
16e80 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
16e90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16ea0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
16eb0 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
16ec0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
16ed0 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
16ee0 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
16ef0 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
16f00 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
16f10 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
16f20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
16f30 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
16f40 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
16f50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16f60 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
16f70 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  4  /* no-op */.#
16f80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16f90 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
16fa0 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    15  /* no-op *
16fb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16fc0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
16fd0 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
16fe0 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  c, void* */.#def
16ff0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17000 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31  G_URI          1
17010 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  7  /* int */.#de
17020 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17030 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20  IG_PCACHE2      
17040 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  18  /* sqlite3_p
17050 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
17060 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17070 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
17080 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c  HE2   19  /* sql
17090 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
170a0 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
170b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
170c0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
170d0 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f  AN 20  /* int */
170e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
170f0 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20  CONFIG_SQLLOG   
17100 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c      21  /* xSqll
17110 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  og, void* */.#de
17120 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17130 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  IG_MMAP_SIZE    
17140 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69  22  /* sqlite3_i
17150 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e  nt64, sqlite3_in
17160 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t64 */.#define S
17170 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
17180 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20  32_HEAPSIZE     
17190 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   23  /* int nByt
171a0 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
171b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
171c0 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32  E_HDRSZ        2
171d0 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a  4  /* int *psz *
171e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
171f0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20  _CONFIG_PMASZ   
17200 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
17210 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20  /* unsigned int 
17220 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65  szPma */.#define
17230 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17240 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20  TMTJRNL_SPILL   
17250 20 20 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42     26  /* int nB
17260 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  yte */../*.** CA
17270 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
17280 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66   Connection Conf
17290 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  iguration Option
172a0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
172b0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
172c0 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
172d0 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
172e0 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
172f0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
17300 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
17310 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
17320 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
17330 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
17340 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61  ** New configura
17350 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79  tion options may
17360 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
17370 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
17380 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74  SQLite..** Exist
17390 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
173a0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20  n options might 
173b0 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e  be discontinued.
173c0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a    Applications.*
173d0 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74  * should check t
173e0 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66  he return code f
173f0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  rom [sqlite3_db_
17400 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
17410 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
17420 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
17430 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64   ^The [sqlite3_d
17440 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
17450 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
17460 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
17470 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
17480 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
17490 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
174a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
174b0 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
174c0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
174d0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
174e0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
174f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
17500 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68   option takes th
17510 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  ree additional a
17520 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
17530 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20  termine the .** 
17540 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72  [lookaside memor
17550 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e  y allocator] con
17560 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74  figuration for t
17570 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
17580 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68  nection]..** ^Th
17590 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
175a0 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61   (the third para
175b0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
175c0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
175d0 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
175e0 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  o a memory buffe
175f0 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f  r to use for loo
17600 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a  kaside memory..*
17610 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
17620 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20  ument after the 
17630 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17640 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a  LOOKASIDE verb.*
17650 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e  * may be NULL in
17660 20 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69   which case SQLi
17670 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65  te will allocate
17680 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64   the.** lookasid
17690 65 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20  e buffer itself 
176a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
176b0 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73  alloc()]. ^The s
176c0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
176d0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
176e0 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
176f0 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54  buffer slot.  ^T
17700 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
17710 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  t is the number 
17720 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68  of.** slots.  Th
17730 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  e size of the bu
17740 66 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73  ffer in the firs
17750 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
17760 62 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a  be greater than.
17770 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74  ** or equal to t
17780 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68  he product of th
17790 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69  e second and thi
177a0 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54  rd arguments.  T
177b0 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73  he buffer.** mus
177c0 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
177d0 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
177e0 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63  ry.  ^If the sec
177f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
17800 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ** SQLITE_DBCONF
17810 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20  IG_LOOKASIDE is 
17820 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f  not a multiple o
17830 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72  f 8, it is inter
17840 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64  nally.** rounded
17850 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78   down to the nex
17860 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70  t smaller multip
17870 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20  le of 8.  ^(The 
17880 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
17890 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
178a0 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65  n for a database
178b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20   connection can 
178c0 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20  only be changed 
178d0 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e  when that.** con
178e0 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63  nection is not c
178f0 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c  urrently using l
17900 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c  ookaside memory,
17910 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72   or in other wor
17920 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22  ds.** when the "
17930 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72  current value" r
17940 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
17950 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73  qlite3_db_status
17960 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ](D,[SQLITE_CONF
17970 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e  IG_LOOKASIDE],..
17980 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41  .) is zero..** A
17990 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68  ny attempt to ch
179a0 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
179b0 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67  de memory config
179c0 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f  uration when loo
179d0 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79  kaside.** memory
179e0 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65   is in use leave
179f0 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  s the configurat
17a00 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e  ion unchanged an
17a10 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53  d returns .** [S
17a20 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f  QLITE_BUSY].)^</
17a30 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
17a40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
17a50 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a  ABLE_FKEY</dt>.*
17a60 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
17a70 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
17a80 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
17a90 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74   the enforcement
17aa0 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   of.** [foreign 
17ab0 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d  key constraints]
17ac0 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  .  There should 
17ad0 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
17ae0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
17af0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
17b00 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
17b10 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
17b20 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  isable FK enforc
17b30 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69  ement,.** positi
17b40 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20  ve to enable FK 
17b50 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e  enforcement or n
17b60 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
17b70 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a   FK enforcement.
17b80 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  ** unchanged.  T
17b90 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17ba0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
17bb0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
17bc0 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
17bd0 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
17be0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
17bf0 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  er FK enforcemen
17c00 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a  t is off or on.*
17c10 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
17c20 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
17c30 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
17c40 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
17c50 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
17c60 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f  case the FK enfo
17c70 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20  rcement setting 
17c80 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
17c90 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
17ca0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
17cb0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
17cc0 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  GGER</dt>.** <dd
17cd0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
17ce0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
17cf0 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45   or disable [CRE
17d00 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
17d10 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72  iggers]..** Ther
17d20 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
17d30 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
17d40 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
17d50 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
17d60 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
17d70 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
17d80 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73  triggers,.** pos
17d90 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
17da0 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61  triggers or nega
17db0 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
17dc0 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e  e setting unchan
17dd0 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ged..** The seco
17de0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
17df0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
17e00 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
17e10 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
17e20 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
17e30 61 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67  ate whether trig
17e40 67 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65  gers are disable
17e50 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
17e60 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
17e70 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
17e80 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
17e90 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
17ea0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
17eb0 73 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73  se the trigger s
17ec0 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
17ed0 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
17ee0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
17ef0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
17f00 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a  BLE_FTS3_TOKENIZ
17f10 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
17f20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
17f30 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
17f40 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 74 77  r disable the tw
17f50 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65  o-argument.** ve
17f60 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74  rsion of the [ft
17f70 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20  s3_tokenizer()] 
17f80 66 75 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69  function which i
17f90 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
17fa0 20 5b 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78   [FTS3] full-tex
17fb0 74 20 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20  t search engine 
17fc0 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68  extension..** Th
17fd0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
17fe0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
17ff0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
18000 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
18010 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
18020 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
18030 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72  e fts3_tokenizer
18040 28 29 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76  () or.** positiv
18050 65 20 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33  e to enable fts3
18060 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20  _tokenizer() or 
18070 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
18080 65 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  e the setting.**
18090 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
180a0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
180b0 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
180c0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
180d0 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
180e0 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
180f0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
18100 65 72 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  er fts3_tokenize
18110 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72  r is disabled or
18120 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
18130 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
18140 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
18150 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
18160 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
18170 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
18180 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69  he new setting i
18190 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
181a0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
181b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
181c0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
181d0 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a  _EXTENSION</dt>.
181e0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
181f0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
18200 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
18210 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
18220 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18230 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e  .** interface in
18240 64 65 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74  dependently of t
18250 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  he [load_extensi
18260 6f 6e 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  on()] SQL functi
18270 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  on..** The [sqli
18280 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
18290 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49  extension()] API
182a0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
182b0 62 6c 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a  bles both the.**
182c0 20 43 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f   C-API [sqlite3_
182d0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
182e0 5d 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  ] and the SQL fu
182f0 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74  nction [load_ext
18300 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68  ension()]..** Th
18310 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
18320 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
18330 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20  uments..** When 
18340 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18350 6e 74 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72  nt to this inter
18360 66 61 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20  face is 1, then 
18370 6f 6e 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69  only the C-API i
18380 73 0a 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64  s.** enabled and
18390 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
183a0 6e 20 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c  n remains disabl
183b0 65 64 2e 20 20 49 66 20 74 68 65 20 66 69 72 73  ed.  If the firs
183c0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  t argument to.**
183d0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
183e0 69 73 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20  is 0, then both 
183f0 74 68 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68  the C-API and th
18400 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61  e SQL function a
18410 72 65 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20  re disabled..** 
18420 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67  If the first arg
18430 75 6d 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65  ument is -1, the
18440 6e 20 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65  n no changes are
18450 20 6d 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f   made to state o
18460 66 20 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20  f either the.** 
18470 43 2d 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c  C-API or the SQL
18480 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
18490 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
184a0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
184b0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
184c0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
184d0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
184e0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
184f0 72 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  r [sqlite3_load_
18500 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
18510 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73  erface.** is dis
18520 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
18530 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
18540 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
18550 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a  d parameter may.
18560 2a 2a 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ** be a NULL poi
18570 6e 74 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63  nter, in which c
18580 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74  ase the new sett
18590 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
185a0 74 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64  ted back..** </d
185b0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
185c0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49  ITE_DBCONFIG_MAI
185d0 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20  NDBNAME</dt>.** 
185e0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
185f0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 68 61  n is used to cha
18600 6e 67 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nge the name of 
18610 74 68 65 20 22 6d 61 69 6e 22 20 64 61 74 61 62  the "main" datab
18620 61 73 65 0a 2a 2a 20 73 63 68 65 6d 61 2e 20 20  ase.** schema.  
18630 5e 54 68 65 20 73 6f 6c 65 20 61 72 67 75 6d 65  ^The sole argume
18640 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
18650 74 6f 20 61 20 63 6f 6e 73 74 61 6e 74 20 55 54  to a constant UT
18660 46 38 20 73 74 72 69 6e 67 0a 2a 2a 20 77 68 69  F8 string.** whi
18670 63 68 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ch will become t
18680 68 65 20 6e 65 77 20 73 63 68 65 6d 61 20 6e 61  he new schema na
18690 6d 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22  me in place of "
186a0 6d 61 69 6e 22 2e 20 20 5e 53 51 4c 69 74 65 0a  main".  ^SQLite.
186b0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6d 61 6b 65  ** does not make
186c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6e   a copy of the n
186d0 65 77 20 6d 61 69 6e 20 73 63 68 65 6d 61 20 6e  ew main schema n
186e0 61 6d 65 20 73 74 72 69 6e 67 2c 20 73 6f 20 74  ame string, so t
186f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
18700 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68  * must ensure th
18710 61 74 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  at the argument 
18720 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 69 73  passed into this
18730 20 44 42 43 4f 4e 46 49 47 20 6f 70 74 69 6f 6e   DBCONFIG option
18740 20 69 73 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a   is unchanged.**
18750 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
18760 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18770 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20  tion closes..** 
18780 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
18790 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
187a0 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45  NO_CKPT_ON_CLOSE
187b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73  </dt>.** <dd> Us
187c0 75 61 6c 6c 79 2c 20 77 68 65 6e 20 61 20 64 61  ually, when a da
187d0 74 61 62 61 73 65 20 69 6e 20 77 61 6c 20 6d 6f  tabase in wal mo
187e0 64 65 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  de is closed or 
187f0 64 65 74 61 63 68 65 64 20 66 72 6f 6d 20 61 20  detached from a 
18800 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 68 61 6e  .** database han
18810 64 6c 65 2c 20 53 51 4c 69 74 65 20 63 68 65 63  dle, SQLite chec
18820 6b 73 20 69 66 20 74 68 69 73 20 77 69 6c 6c 20  ks if this will 
18830 6d 65 61 6e 20 74 68 61 74 20 74 68 65 72 65 20  mean that there 
18840 61 72 65 20 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63  are now no .** c
18850 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 74 20 61 6c  onnections at al
18860 6c 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  l to the databas
18870 65 2e 20 49 66 20 73 6f 2c 20 69 74 20 70 65 72  e. If so, it per
18880 66 6f 72 6d 73 20 61 20 63 68 65 63 6b 70 6f 69  forms a checkpoi
18890 6e 74 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  nt .** operation
188a0 20 62 65 66 6f 72 65 20 63 6c 6f 73 69 6e 67 20   before closing 
188b0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
188c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 6d 61 79 20  This option may 
188d0 62 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 6f 76  be used to.** ov
188e0 65 72 72 69 64 65 20 74 68 69 73 20 62 65 68 61  erride this beha
188f0 76 69 6f 75 72 2e 20 54 68 65 20 66 69 72 73 74  viour. The first
18900 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
18910 64 20 74 6f 20 74 68 69 73 20 6f 70 65 72 61 74  d to this operat
18920 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e 20 69 6e 74  ion.** is an int
18930 65 67 65 72 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20  eger - non-zero 
18940 74 6f 20 64 69 73 61 62 6c 65 20 63 68 65 63 6b  to disable check
18950 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c  points-on-close,
18960 20 6f 72 20 7a 65 72 6f 20 28 74 68 65 0a 2a 2a   or zero (the.**
18970 20 64 65 66 61 75 6c 74 29 20 74 6f 20 65 6e 61   default) to ena
18980 62 6c 65 20 74 68 65 6d 2e 20 54 68 65 20 73 65  ble them. The se
18990 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
189a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
189b0 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 69 6e 74  n integer.** int
189c0 6f 20 77 68 69 63 68 20 69 73 20 77 72 69 74 74  o which is writt
189d0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
189e0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 63 68  icate whether ch
189f0 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f  eckpoints-on-clo
18a00 73 65 0a 2a 2a 20 68 61 76 65 20 62 65 65 6e 20  se.** have been 
18a10 64 69 73 61 62 6c 65 64 20 2d 20 30 20 69 66 20  disabled - 0 if 
18a20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 64 69 73  they are not dis
18a30 61 62 6c 65 64 2c 20 31 20 69 66 20 74 68 65 79  abled, 1 if they
18a40 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a   are..** </dd>.*
18a50 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18a60 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18a70 51 50 53 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  QPSG</dt>.** <dd
18a80 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 44 42  >^(The SQLITE_DB
18a90 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50  CONFIG_ENABLE_QP
18aa0 53 47 20 6f 70 74 69 6f 6e 20 61 63 74 69 76 61  SG option activa
18ab0 74 65 73 20 6f 72 20 64 65 61 63 74 69 76 61 74  tes or deactivat
18ac0 65 73 0a 2a 2a 20 74 68 65 20 5b 71 75 65 72 79  es.** the [query
18ad0 20 70 6c 61 6e 6e 65 72 20 73 74 61 62 69 6c 69   planner stabili
18ae0 74 79 20 67 75 61 72 61 6e 74 65 65 5d 20 28 51  ty guarantee] (Q
18af0 50 53 47 29 2e 20 20 57 68 65 6e 20 74 68 65 20  PSG).  When the 
18b00 51 50 53 47 20 69 73 20 61 63 74 69 76 65 2c 0a  QPSG is active,.
18b10 2a 2a 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ** a single SQL 
18b20 71 75 65 72 79 20 73 74 61 74 65 6d 65 6e 74 20  query statement 
18b30 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20  will always use 
18b40 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
18b50 68 6d 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  hm regardless.**
18b60 20 6f 66 20 76 61 6c 75 65 73 20 6f 66 20 5b 62   of values of [b
18b70 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d  ound parameters]
18b80 2e 29 5e 20 54 68 65 20 51 50 53 47 20 64 69 73  .)^ The QPSG dis
18b90 61 62 6c 65 73 20 73 6f 6d 65 20 71 75 65 72 79  ables some query
18ba0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 0a 2a   optimizations.*
18bb0 2a 20 74 68 61 74 20 6c 6f 6f 6b 20 61 74 20 74  * that look at t
18bc0 68 65 20 76 61 6c 75 65 73 20 6f 66 20 62 6f 75  he values of bou
18bd0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 2c 20 77  nd parameters, w
18be0 68 69 63 68 20 63 61 6e 20 6d 61 6b 65 20 73 6f  hich can make so
18bf0 6d 65 20 71 75 65 72 69 65 73 0a 2a 2a 20 73 6c  me queries.** sl
18c00 6f 77 65 72 2e 20 20 42 75 74 20 74 68 65 20 51  ower.  But the Q
18c10 50 53 47 20 68 61 73 20 74 68 65 20 61 64 76 61  PSG has the adva
18c20 6e 74 61 67 65 20 6f 66 20 6d 6f 72 65 20 70 72  ntage of more pr
18c30 65 64 69 63 74 61 62 6c 65 20 62 65 68 61 76 69  edictable behavi
18c40 6f 72 2e 20 20 57 69 74 68 0a 2a 2a 20 74 68 65  or.  With.** the
18c50 20 51 50 53 47 20 61 63 74 69 76 65 2c 20 53 51   QPSG active, SQ
18c60 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
18c70 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 71 75   use the same qu
18c80 65 72 79 20 70 6c 61 6e 20 69 6e 20 74 68 65 20  ery plan in the 
18c90 66 69 65 6c 64 20 61 73 0a 2a 2a 20 77 61 73 20  field as.** was 
18ca0 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
18cb0 69 6e 67 20 69 6e 20 74 68 65 20 6c 61 62 2e 0a  ing in the lab..
18cc0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </dd>.**.** <
18cd0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
18ce0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18cf0 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20  MAINDBNAME      
18d00 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f        1000 /* co
18d10 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65  nst char* */.#de
18d20 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18d30 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
18d40 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20             1001 
18d50 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74  /* void* int int
18d60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18d70 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18d80 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20  LE_FKEY         
18d90 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e    1002 /* int in
18da0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18db0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18dc0 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20  ABLE_TRIGGER    
18dd0 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20      1003 /* int 
18de0 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18df0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18e00 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45  ENABLE_FTS3_TOKE
18e10 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e  NIZER 1004 /* in
18e20 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
18e30 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18e40 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58  G_ENABLE_LOAD_EX
18e50 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20  TENSION 1005 /* 
18e60 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
18e70 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
18e80 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43  FIG_NO_CKPT_ON_C
18e90 4c 4f 53 45 20 20 20 20 20 20 31 30 30 36 20 2f  LOSE      1006 /
18ea0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
18eb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
18ec0 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53  ONFIG_ENABLE_QPS
18ed0 47 20 20 20 20 20 20 20 20 20 20 20 31 30 30 37  G           1007
18ee0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
18ef0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18f00 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
18f10 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
18f20 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54  ult Codes.** MET
18f30 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
18f40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18f50 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
18f60 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
18f70 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
18f80 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
18f90 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
18fa0 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
18fb0 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
18fc0 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
18fd0 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
18fe0 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
18ff0 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
19000 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74  tibility..*/.int
19010 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
19020 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
19030 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
19040 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
19050 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
19060 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f  t Rowid.** METHO
19070 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19080 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
19090 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c  most SQLite tabl
190a0 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b  es (except for [
190b0 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
190c0 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20  ables).** has a 
190d0 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
190e0 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
190f0 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
19100 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
19110 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
19120 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
19130 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
19140 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
19150 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
19160 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
19170 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
19180 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
19190 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
191a0 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
191b0 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
191c0 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
191d0 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
191e0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
191f0 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
19200 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
19210 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
19220 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  wid..**.** ^The 
19230 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
19240 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74  ert_rowid(D) int
19250 65 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20 72  erface usually r
19260 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
19270 64 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f 73  d] of.** the mos
19280 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
19290 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
192a0 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20  o a rowid table 
192b0 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  or [virtual tabl
192c0 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73  e].** on databas
192d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
192e0 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
192f0 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
19300 62 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  bles are not.** 
19310 72 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e 6f  recorded. ^If no
19320 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
19330 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
19340 20 74 61 62 6c 65 73 20 68 61 76 65 20 65 76 65   tables have eve
19350 72 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20 6f  r occurred .** o
19360 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
19370 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68 65  onnection D, the
19380 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  n sqlite3_last_i
19390 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72  nsert_rowid(D) r
193a0 65 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f 2e  eturns .** zero.
193b0 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20 61  .**.** As well a
193c0 73 20 62 65 69 6e 67 20 73 65 74 20 61 75 74 6f  s being set auto
193d0 6d 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f 77  matically as row
193e0 73 20 61 72 65 20 69 6e 73 65 72 74 65 64 20 69  s are inserted i
193f0 6e 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  nto database.** 
19400 74 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c 75  tables, the valu
19410 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
19420 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  is function may 
19430 62 65 20 73 65 74 20 65 78 70 6c 69 63 69 74 6c  be set explicitl
19440 79 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  y by.** [sqlite3
19450 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74  _set_last_insert
19460 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a 20  _rowid()].**.** 
19470 53 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61 62  Some virtual tab
19480 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
19490 6e 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72 6f  ns may INSERT ro
194a0 77 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61  ws into rowid ta
194b0 62 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74 20  bles as.** part 
194c0 6f 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61 20  of committing a 
194d0 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e 67  transaction (e.g
194e0 2e 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  . to flush data 
194f0 61 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20 6d  accumulated in m
19500 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73 6b  emory.** to disk
19510 29 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 20  ). In this case 
19520 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
19530 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f   to this functio
19540 6e 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f 77  n return the row
19550 69 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  id.** associated
19560 20 77 69 74 68 20 74 68 65 73 65 20 69 6e 74 65   with these inte
19570 72 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65 72  rnal INSERT oper
19580 61 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c 65  ations, which le
19590 61 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e 74  ads to .** unint
195a0 75 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e 20  uitive results. 
195b0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
195c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 68  plementations th
195d0 61 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20 72  at do write to r
195e0 6f 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20 69  owid.** tables i
195f0 6e 20 74 68 69 73 20 77 61 79 20 63 61 6e 20 61  n this way can a
19600 76 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c 65  void this proble
19610 6d 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20 74  m by restoring t
19620 68 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a 20  he original .** 
19630 72 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69 6e  rowid value usin
19640 67 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c  g [sqlite3_set_l
19650 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19660 28 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75 72  ()] before retur
19670 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f 6c  ning .** control
19680 20 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a 2a   to the user..**
19690 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
196a0 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
196b0 69 6e 20 61 20 74 72 69 67 67 65 72 20 74 68 65  in a trigger the
196c0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
196d0 69 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20 74  ill .** return t
196e0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
196f0 65 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20 61  e inserted row a
19700 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
19710 69 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75 6e  igger is .** run
19720 6e 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20 74  ning. Once the t
19730 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65  rigger program e
19740 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
19750 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
19760 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
19770 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
19780 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
19790 69 67 67 65 72 20 77 61 73 20 66 69 72 65 64 2e  igger was fired.
197a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
197b0 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
197c0 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
197d0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
197e0 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
197f0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
19800 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
19810 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
19820 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
19830 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
19840 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
19850 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
19860 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
19870 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
19880 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
19890 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
198a0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
198b0 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
198c0 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
198d0 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
198e0 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
198f0 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
19900 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
19910 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
19920 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
19930 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
19940 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
19950 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
19960 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
19970 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
19980 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
19990 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
199a0 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
199b0 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
199c0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
199d0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
199e0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
199f0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
19a00 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
19a10 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
19a20 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
19a30 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
19a40 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
19a50 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
19a60 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
19a70 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
19a80 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
19a90 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
19aa0 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
19ab0 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
19ac0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
19ad0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
19ae0 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
19af0 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
19b00 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
19b10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
19b20 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
19b30 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19b40 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
19b50 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
19b60 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
19b70 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
19b80 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
19b90 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19ba0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
19bb0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
19bc0 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
19bd0 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
19be0 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
19bf0 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
19c00 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
19c10 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
19c20 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
19c30 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
19c40 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
19c50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19c60 46 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20  F: Set the Last 
19c70 49 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c  Insert Rowid val
19c80 75 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ue..** METHOD: s
19c90 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
19ca0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73   sqlite3_set_las
19cb0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
19cc0 2c 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f  , R) method allo
19cd0 77 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ws the applicati
19ce0 6f 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65  on to.** set the
19cf0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
19d00 62 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  by calling sqlit
19d10 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
19d20 6f 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a  owid(D) to R .**
19d30 20 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69   without inserti
19d40 6e 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68  ng a row into th
19d50 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 76  e database..*/.v
19d60 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
19d70 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19d80 64 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 74  d(sqlite3*,sqlit
19d90 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a  e3_int64);../*.*
19da0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e  * CAPI3REF: Coun
19db0 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20  t The Number Of 
19dc0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
19dd0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
19de0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
19df0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
19e00 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
19e10 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 72   modified, inser
19e20 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65  ted or.** delete
19e30 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
19e40 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
19e50 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
19e60 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
19e70 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 61  tement on the da
19e80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19e90 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  n specified by t
19ea0 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
19eb0 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67  r..** ^Executing
19ec0 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
19ed0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
19ee0 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79   does not modify
19ef0 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
19f00 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66  turned by this f
19f10 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
19f20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64  Only changes mad
19f30 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 68  e directly by th
19f40 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  e INSERT, UPDATE
19f50 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
19f60 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73  ment are.** cons
19f70 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 61  idered - auxilia
19f80 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
19f90 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 49  d by [CREATE TRI
19fa0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
19fb0 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  , .** [foreign k
19fc0 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b  ey actions] or [
19fd0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
19fe0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
19ff0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a  re not counted..
1a000 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74  ** .** Changes t
1a010 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
1a020 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79  e intercepted by
1a030 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46   .** [INSTEAD OF
1a040 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 45   trigger | INSTE
1a050 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d 20  AD OF triggers] 
1a060 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1a070 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20   ^The value .** 
1a080 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1a090 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6d  te3_changes() im
1a0a0 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 20  mediately after 
1a0b0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1a0c0 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20  E or .** DELETE 
1a0d0 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e  statement run on
1a0e0 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 79   a view is alway
1a0f0 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61  s zero. Only cha
1a100 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 61  nges made to rea
1a110 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 65  l .** tables are
1a120 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20   counted..**.** 
1a130 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 20  Things are more 
1a140 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 74  complicated if t
1a150 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
1a160 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1a170 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 69  .** executed whi
1a180 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  le a trigger pro
1a190 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gram is running.
1a1a0 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 6e   This may happen
1a1b0 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72   if the.** progr
1a1c0 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 61  am uses the [cha
1a1d0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1a1e0 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65  ion], or if some
1a1f0 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a   other callback.
1a200 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f  ** function invo
1a210 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  kes sqlite3_chan
1a220 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e 20  ges() directly. 
1a230 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20  Essentially:.** 
1a240 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
1a250 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 65  i> ^(Before ente
1a260 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 70  ring a trigger p
1a270 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 65  rogram the value
1a280 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1a290 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63         sqlite3_c
1a2a0 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
1a2b0 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 65  n is saved. Afte
1a2c0 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72  r the trigger pr
1a2d0 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20  ogram .**       
1a2e0 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 74   has finished, t
1a2f0 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75  he original valu
1a300 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 5e  e is restored.)^
1a310 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  .** .**   <li> ^
1a320 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 65  (Within a trigge
1a330 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 49  r program each I
1a340 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 6e  NSERT, UPDATE an
1a350 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20  d DELETE .**    
1a360 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 65      statement se
1a370 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ts the value ret
1a380 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1a390 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20  _changes() .**  
1a3a0 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c        upon compl
1a3b0 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e  etion as normal.
1a3c0 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 73   Of course, this
1a3d0 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20   value will not 
1a3e0 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20  include .**     
1a3f0 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 70     any changes p
1a400 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 2d  erformed by sub-
1a410 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 65  triggers, as the
1a420 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a430 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 61  () .**        va
1a440 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 65  lue will be save
1a450 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 61  d and restored a
1a460 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 72  fter each sub-tr
1a470 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 5e  igger has run.)^
1a480 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a  .** </ul>.** .**
1a490 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61   ^This means tha
1a4a0 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 73  t if the changes
1a4b0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  () SQL function 
1a4c0 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 20  (or similar) is 
1a4d0 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66  used.** by the f
1a4e0 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 44  irst INSERT, UPD
1a4f0 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1a500 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
1a510 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a   trigger, it .**
1a520 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
1a530 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 74  ue as set when t
1a540 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 65  he calling state
1a550 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 75  ment began execu
1a560 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20  ting..** ^If it 
1a570 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 73  is used by the s
1a580 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 75  econd or subsequ
1a590 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d 65  ent such stateme
1a5a0 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  nt within a trig
1a5b0 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c  ger .** program,
1a5c0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a5d0 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 65  ned reflects the
1a5e0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1a5f0 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 20  modified by the 
1a600 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e 53  .** previous INS
1a610 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1a620 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1a630 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
1a640 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53  trigger..**.** S
1a650 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1a660 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1a670 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
1a680 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
1a690 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
1a6a0 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
1a6b0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1a6c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1a6d0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1a6e0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1a6f0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1a700 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1a710 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
1a720 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
1a730 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
1a740 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
1a750 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
1a760 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
1a770 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
1a780 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
1a790 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
1a7a0 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
1a7b0 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
1a7c0 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ied.** METHOD: s
1a7d0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1a7e0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1a7f0 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  rns the total nu
1a800 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73  mber of rows ins
1a810 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20  erted, modified 
1a820 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
1a830 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   all [INSERT], [
1a840 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
1a850 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63  TE] statements c
1a860 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63  ompleted.** sinc
1a870 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1a880 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70  onnection was op
1a890 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ened, including 
1a8a0 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61  those executed a
1a8b0 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69  s.** part of tri
1a8c0 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e  gger programs. ^
1a8d0 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
1a8e0 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
1a8f0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65  statement.** doe
1a900 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65  s not affect the
1a910 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1a920 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
1a930 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a  _changes()..** .
1a940 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65  ** ^Changes made
1a950 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72   as part of [for
1a960 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
1a970 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69  ] are included i
1a980 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20  n the.** count, 
1a990 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61  but those made a
1a9a0 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43  s part of REPLAC
1a9b0 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  E constraint res
1a9c0 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e  olution are.** n
1a9d0 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  ot. ^Changes to 
1a9e0 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
1a9f0 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49  intercepted by I
1aa00 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
1aa10 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  rs .** are not c
1aa20 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53  ounted..** .** S
1aa30 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
1aa40 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
1aa50 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1aa60 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1aa70 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1aa80 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
1aa90 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1aaa0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
1aab0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
1aac0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
1aad0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
1aae0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
1aaf0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
1ab00 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
1ab10 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
1ab20 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
1ab30 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
1ab40 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
1ab50 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
1ab60 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1ab70 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1ab80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ab90 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
1aba0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
1abb0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1abc0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1abd0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
1abe0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
1abf0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
1ac00 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
1ac10 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
1ac20 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
1ac30 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
1ac40 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
1ac50 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
1ac60 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
1ac70 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
1ac80 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
1ac90 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
1aca0 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
1acb0 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
1acc0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
1acd0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
1ace0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
1acf0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1ad00 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
1ad10 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
1ad20 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
1ad30 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
1ad40 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
1ad50 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1ad60 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
1ad70 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
1ad80 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
1ad90 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1ada0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
1adb0 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
1adc0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
1add0 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
1ade0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
1adf0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
1ae00 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
1ae10 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
1ae20 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
1ae30 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
1ae40 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
1ae50 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
1ae60 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
1ae70 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
1ae80 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
1ae90 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
1aea0 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
1aeb0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
1aec0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
1aed0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
1aee0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
1aef0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
1af00 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
1af10 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
1af20 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
1af30 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
1af40 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
1af50 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
1af60 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
1af70 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
1af80 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
1af90 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
1afa0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
1afb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1afc0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1afd0 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
1afe0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
1aff0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
1b000 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1b010 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
1b020 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
1b030 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
1b040 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1b050 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1b060 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
1b070 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1b080 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
1b090 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
1b0a0 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
1b0b0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
1b0c0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
1b0d0 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
1b0e0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
1b0f0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
1b100 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
1b110 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
1b120 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1b130 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1b140 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
1b150 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
1b160 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
1b170 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
1b180 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1b190 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
1b1a0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
1b1b0 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
1b1c0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
1b1d0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
1b1e0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1b1f0 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
1b200 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
1b210 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
1b220 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1b230 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1b240 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b250 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
1b260 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
1b270 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
1b280 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1b290 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
1b2a0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
1b2b0 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
1b2c0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
1b2d0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
1b2e0 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
1b2f0 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
1b300 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
1b310 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
1b320 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
1b330 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
1b340 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1b350 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
1b360 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
1b370 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
1b380 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
1b390 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
1b3a0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
1b3b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1b3c0 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
1b3d0 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
1b3e0 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
1b3f0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1b400 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
1b410 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
1b420 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
1b430 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
1b440 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
1b450 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
1b460 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
1b470 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
1b480 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
1b490 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
1b4a0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
1b4b0 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
1b4c0 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
1b4d0 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
1b4e0 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
1b4f0 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
1b500 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
1b510 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
1b520 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
1b530 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
1b540 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
1b550 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
1b560 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
1b570 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
1b580 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
1b590 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
1b5a0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
1b5b0 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
1b5c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1b5d0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1b5e0 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
1b5f0 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
1b600 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
1b610 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
1b620 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
1b630 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
1b640 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
1b650 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
1b660 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
1b670 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
1b680 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
1b690 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
1b6a0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
1b6b0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
1b6c0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
1b6d0 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
1b6e0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
1b6f0 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
1b700 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
1b710 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1b720 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
1b730 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
1b740 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
1b750 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
1b760 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1b770 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
1b780 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
1b790 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
1b7a0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
1b7b0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1b7c0 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
1b7d0 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
1b7e0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1b7f0 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
1b800 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
1b810 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
1b820 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1b830 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
1b840 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
1b850 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
1b860 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
1b870 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1b880 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
1b890 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1b8a0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1b8b0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
1b8c0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
1b8d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
1b8e0 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
1b8f0 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
1b900 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1b910 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
1b920 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b930 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
1b940 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
1b950 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
1b960 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  rors.** KEYWORDS
1b970 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20  : {busy-handler 
1b980 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20  callback} {busy 
1b990 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48  handler}.** METH
1b9a0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1b9b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
1b9c0 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c  usy_handler(D,X,
1b9d0 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  P) routine sets 
1b9e0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1b9f0 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69  ion X.** that mi
1ba00 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
1ba10 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
1ba20 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
1ba30 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
1ba40 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61   access a databa
1ba50 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61  se table associa
1ba60 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74  ted with.** [dat
1ba70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ba80 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72  ] D when another
1ba90 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
1baa0 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61  ocess has the ta
1bab0 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54  ble locked..** T
1bac0 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
1bad0 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66  handler() interf
1bae0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69  ace is used to i
1baf0 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c  mplement.** [sql
1bb00 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1bb10 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41  t()] and [PRAGMA
1bb20 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a   busy_timeout]..
1bb30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
1bb40 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1bb50 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
1bb60 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65  E_BUSY].** is re
1bb70 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1bb80 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
1bb90 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
1bba0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1bbb0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
1bbc0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
1bbd0 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
1bbe0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
1bbf0 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
1bc00 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1bc10 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
1bc20 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
1bc30 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
1bc40 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
1bc50 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
1bc60 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1bc70 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1bc80 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
1bc90 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1bca0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1bcb0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1bcc0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
1bcd0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
1bce0 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
1bcf0 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69  en invoked previ
1bd00 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61  ously for the sa
1bd10 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
1bd20 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
1bd30 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
1bd40 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
1bd50 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
1bd60 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
1bd70 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
1bd80 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
1bd90 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72  E_BUSY] is retur
1bda0 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  ned.** to the ap
1bdb0 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  plication..** ^I
1bdc0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
1bdd0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1bde0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
1bdf0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
1be00 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
1be10 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20  atabase and the 
1be20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
1be30 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
1be40 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
1be50 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
1be60 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
1be70 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
1be80 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
1be90 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
1bea0 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
1beb0 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
1bec0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
1bed0 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
1bee0 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
1bef0 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
1bf00 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
1bf10 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1bf20 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1bf30 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20  tion instead of 
1bf40 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a  invoking the .**
1bf50 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1bf60 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
1bf70 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
1bf80 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1bf90 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
1bfa0 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
1bfb0 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
1bfc0 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
1bfd0 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
1bfe0 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
1bff0 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
1c000 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
1c010 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
1c020 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
1c030 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
1c040 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
1c050 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
1c060 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1c070 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
1c080 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
1c090 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
1c0a0 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
1c0b0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1c0c0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
1c0d0 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
1c0e0 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
1c0f0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
1c100 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
1c110 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
1c120 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
1c130 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
1c140 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
1c150 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1c160 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
1c170 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
1c180 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
1c190 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
1c1a0 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
1c1b0 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
1c1c0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
1c1d0 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
1c1e0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
1c1f0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1c200 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ULL..**.** ^(The
1c210 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1c220 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1c230 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
1c240 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
1c250 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1c260 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
1c270 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
1c280 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
1c290 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
1c2a0 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
1c2b0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1c2c0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1c2d0 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  .** or evaluatin
1c2e0 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  g [PRAGMA busy_t
1c2f0 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63  imeout=N] will c
1c300 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73  hange the.** bus
1c310 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68  y handler and th
1c320 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65  us clear any pre
1c330 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79  viously set busy
1c340 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1c350 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
1c360 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
1c370 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
1c380 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
1c390 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1c3a0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1c3b0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1c3c0 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ler.  In other w
1c3d0 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73  ords,.** the bus
1c3e0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74  y handler is not
1c3f0 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79   reentrant.  Any
1c400 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
1c410 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
1c420 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
1c430 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
1c440 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
1c450 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
1c460 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1c470 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
1c480 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
1c490 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1c4a0 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
1c4b0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1c4c0 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a  r(sqlite3*,int(*
1c4d0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69  )(void*,int),voi
1c4e0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1c4f0 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
1c500 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48   Timeout.** METH
1c510 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1c520 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1c530 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
1c540 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
1c550 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
1c560 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
1c570 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
1c580 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
1c590 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
1c5a0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
1c5b0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
1c5c0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
1c5d0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
1c5e0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1c5f0 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
1c600 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
1c610 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
1c620 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1c630 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
1c640 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
1c650 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
1c660 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
1c670 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
1c680 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
1c690 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
1c6a0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
1c6b0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
1c6c0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
1c6d0 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
1c6e0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
1c6f0 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
1c700 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1c710 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1c720 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
1c730 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1c740 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c750 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65  ion] at any give
1c760 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
1c770 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1c780 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
1c790 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
1c7a0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1c7b0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
1c7c0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
1c7d0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
1c7e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1c7f0 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a   cleared.)^.**.*
1c800 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52  * See also:  [PR
1c810 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1c820 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t].*/.int sqlite
1c830 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
1c840 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
1c850 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c860 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
1c870 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
1c880 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d  ing Queries.** M
1c890 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1c8a0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
1c8b0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
1c8c0 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
1c8d0 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
1c8e0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1c8f0 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
1c900 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
1c910 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
1c920 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
1c930 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
1c940 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
1c950 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
1c960 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
1c970 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1c980 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
1c990 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1c9a0 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
1c9b0 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
1c9c0 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
1c9d0 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
1c9e0 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
1c9f0 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
1ca00 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
1ca10 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
1ca20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
1ca30 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
1ca40 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
1ca50 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
1ca60 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
1ca70 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
1ca80 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
1ca90 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1caa0 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
1cab0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1cac0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
1cad0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1cae0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
1caf0 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
1cb00 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
1cb10 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
1cb20 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
1cb30 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
1cb40 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
1cb50 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
1cb60 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
1cb70 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1cb80 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
1cb90 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
1cba0 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
1cbb0 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
1cbc0 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
1cbd0 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
1cbe0 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
1cbf0 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
1cc00 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
1cc10 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
1cc20 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
1cc30 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1cc40 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
1cc50 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
1cc60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1cc70 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
1cc80 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
1cc90 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
1cca0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
1ccb0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
1ccc0 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
1ccd0 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
1cce0 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
1ccf0 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
1cd00 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
1cd10 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
1cd20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
1cd30 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
1cd40 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
1cd50 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
1cd60 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
1cd70 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
1cd80 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
1cd90 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
1cda0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1cdb0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1cdc0 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
1cdd0 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
1cde0 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
1cdf0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
1ce00 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
1ce10 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
1ce20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
1ce30 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
1ce40 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
1ce50 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ce60 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
1ce70 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
1ce80 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
1ce90 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
1cea0 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
1ceb0 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
1cec0 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
1ced0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1cee0 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
1cef0 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
1cf00 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
1cf10 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
1cf20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
1cf30 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1cf40 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1cf50 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
1cf60 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
1cf70 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1cf80 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
1cf90 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1cfa0 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
1cfb0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1cfc0 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
1cfd0 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
1cfe0 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
1cff0 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
1d000 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
1d010 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
1d020 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1d030 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
1d040 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1d050 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
1d060 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1d070 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
1d080 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1d090 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
1d0a0 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
1d0b0 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
1d0c0 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
1d0d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
1d0e0 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
1d0f0 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
1d100 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
1d110 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
1d120 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
1d130 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
1d140 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
1d150 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
1d160 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
1d170 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
1d180 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1d190 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
1d1a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1d1b0 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
1d1c0 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
1d1d0 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
1d1e0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1d1f0 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
1d200 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
1d210 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
1d220 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
1d230 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
1d240 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
1d250 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
1d260 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
1d270 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
1d280 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
1d290 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
1d2a0 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
1d2b0 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
1d2c0 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
1d2d0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1d2e0 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
1d2f0 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1d300 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
1d310 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
1d320 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1d330 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
1d340 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
1d350 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
1d360 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
1d370 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
1d380 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d390 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
1d3a0 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
1d3b0 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
1d3c0 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
1d3d0 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
1d3e0 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
1d3f0 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
1d400 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
1d410 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
1d420 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
1d430 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
1d440 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
1d450 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
1d460 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
1d470 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
1d480 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
1d490 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
1d4a0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1d4b0 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
1d4c0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1d4d0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1d4e0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1d4f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1d500 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1d510 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1d520 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1d530 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1d540 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1d550 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1d560 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1d570 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1d580 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1d590 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1d5a0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1d5b0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1d5c0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1d5d0 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1d5e0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1d5f0 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1d600 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1d610 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1d620 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1d630 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1d640 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1d650 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
1d660 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
1d670 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
1d680 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
1d690 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1d6a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1d6b0 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
1d6c0 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
1d6d0 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
1d6e0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
1d6f0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1d700 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65  ibrary..** These
1d710 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73   routines unders
1d720 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65  tand most of the
1d730 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d   common K&R form
1d740 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a  atting options,.
1d750 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64  ** plus some add
1d760 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e  itional non-stan
1d770 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65  dard formats, de
1d780 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a  tailed below..**
1d790 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20   Note that some 
1d7a0 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63  of the more obsc
1d7b0 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  ure formatting o
1d7c0 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65  ptions from rece
1d7d0 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20  nt.** C-library 
1d7e0 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d  standards are om
1d7f0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20  itted from this 
1d800 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a  implementation..
1d810 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1d820 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
1d830 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
1d840 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
1d850 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
1d860 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
1d870 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
1d880 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1d890 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
1d8a0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1d8b0 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
1d8c0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
1d8d0 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
1d8e0 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
1d8f0 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
1d900 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
1d910 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
1d920 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
1d930 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1d940 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
1d950 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
1d960 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
1d970 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1d980 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
1d990 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
1d9a0 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
1d9b0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
1d9c0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
1d9d0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
1d9e0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1d9f0 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
1da00 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
1da10 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
1da20 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
1da30 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
1da40 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
1da50 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
1da60 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
1da70 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
1da80 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
1da90 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
1daa0 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
1dab0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
1dac0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
1dad0 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
1dae0 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
1daf0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1db00 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
1db10 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
1db20 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
1db30 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
1db40 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
1db50 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
1db60 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
1db70 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
1db80 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
1db90 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
1dba0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
1dbb0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
1dbc0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
1dbd0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
1dbe0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
1dbf0 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
1dc00 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
1dc10 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
1dc20 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1dc30 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
1dc40 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
1dc50 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
1dc60 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
1dc70 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
1dc80 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
1dc90 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1dca0 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
1dcb0 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
1dcc0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
1dcd0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
1dce0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1dcf0 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
1dd00 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
1dd10 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
1dd20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
1dd30 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
1dd40 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
1dd50 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
1dd60 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
1dd70 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
1dd80 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
1dd90 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1dda0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1ddb0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
1ddc0 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
1ddd0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1dde0 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
1ddf0 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
1de00 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
1de10 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
1de20 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
1de30 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
1de40 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
1de50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1de60 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
1de70 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
1de80 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
1de90 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
1dea0 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
1deb0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
1dec0 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f   "%w" and "%z" o
1ded0 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
1dee0 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
1def0 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
1df00 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
1df10 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  es a nul-termina
1df20 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
1df30 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
1df40 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
1df50 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
1df60 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
1df70 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
1df80 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
1df90 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
1dfa0 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69  al.)^  By doubli
1dfb0 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
1dfc0 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
1dfd0 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
1dfe0 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
1dff0 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
1e000 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
1e010 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
1e020 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
1e030 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
1e040 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
1e050 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
1e060 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1e070 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1e080 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
1e090 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
1e0a0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1e0b0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
1e0c0 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
1e0d0 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
1e0e0 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
1e0f0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1e100 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1e110 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1e120 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1e130 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1e140 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
1e150 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1e160 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1e170 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1e180 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1e190 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1e1a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1e1b0 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
1e1c0 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
1e1d0 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
1e1e0 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
1e1f0 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
1e200 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
1e210 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
1e220 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1e230 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1e240 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1e250 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1e260 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
1e270 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
1e280 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1e290 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
1e2a0 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
1e2b0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
1e2c0 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
1e2d0 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
1e2e0 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
1e2f0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e300 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1e310 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1e320 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
1e330 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
1e340 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1e350 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1e360 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
1e370 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
1e380 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
1e390 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
1e3a0 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
1e3b0 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
1e3c0 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
1e3d0 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
1e3e0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
1e3f0 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70  *.** ^(The %Q op
1e400 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1e410 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
1e420 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
1e430 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
1e440 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
1e450 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
1e460 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
1e470 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1e480 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
1e490 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
1e4a0 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
1e4b0 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
1e4c0 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
1e4d0 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
1e4e0 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72  tes).)^  So, for
1e4f0 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
1e500 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
1e510 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1e520 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1e530 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1e540 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1e550 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
1e560 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1e570 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1e580 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1e590 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1e5a0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1e5b0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1e5c0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
1e5d0 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
1e5e0 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
1e5f0 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
1e600 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
1e610 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
1e620 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
1e630 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1e640 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f  ** ^(The "%w" fo
1e650 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1e660 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63  is like "%q" exc
1e670 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65  ept that it expe
1e680 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e  cts to.** be con
1e690 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f  tained within do
1e6a0 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74  uble-quotes inst
1e6b0 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75  ead of single qu
1e6c0 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20  otes, and it.** 
1e6d0 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62  escapes the doub
1e6e0 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74  le-quote charact
1e6f0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
1e700 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a  e single-quote.*
1e710 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20  * character.)^  
1e720 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74  The "%w" formatt
1e730 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e  ing option is in
1e740 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c  tended for safel
1e750 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74  y inserting.** t
1e760 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  able and column 
1e770 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e  names into a con
1e780 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61  structed SQL sta
1e790 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tement..**.** ^(
1e7a0 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
1e7b0 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
1e7c0 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
1e7d0 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
1e7e0 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
1e7f0 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
1e800 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
1e810 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
1e820 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
1e830 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
1e840 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
1e850 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
1e860 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
1e870 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
1e880 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
1e890 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1e8a0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1e8b0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
1e8c0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1e8d0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1e8e0 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
1e8f0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
1e900 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1e910 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
1e920 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e930 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
1e940 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
1e950 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
1e960 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
1e970 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
1e980 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
1e990 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
1e9a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
1e9b0 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
1e9c0 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
1e9d0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
1e9e0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
1e9f0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
1ea00 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
1ea10 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
1ea20 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
1ea30 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
1ea40 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
1ea50 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
1ea60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1ea70 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
1ea80 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
1ea90 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
1eaa0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
1eab0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1eac0 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
1ead0 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
1eae0 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
1eaf0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
1eb00 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
1eb10 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
1eb20 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
1eb30 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1eb40 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
1eb50 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
1eb60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1eb70 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
1eb80 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
1eb90 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
1eba0 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
1ebb0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
1ebc0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1ebd0 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72  4(N) routine wor
1ebe0 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20  ks just like.** 
1ebf0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e  sqlite3_malloc(N
1ec00 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
1ec10 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36  is an unsigned 6
1ec20 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e  4-bit integer in
1ec30 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69  stead.** of a si
1ec40 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65  gned 32-bit inte
1ec50 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ger..**.** ^Call
1ec60 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1ec70 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1ec80 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1ec90 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1eca0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1ecb0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ecc0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1ecd0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1ece0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1ecf0 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1ed00 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1ed10 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1ed20 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1ed30 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1ed40 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1ed50 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1ed60 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1ed70 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1ed80 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1ed90 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1eda0 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1edb0 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1edc0 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1edd0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1ede0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1edf0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1ee00 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1ee10 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1ee20 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1ee30 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1ee40 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1ee50 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1ee60 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1ee70 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1ee80 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1ee90 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1eea0 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1eeb0 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1eec0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1eed0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1eee0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1eef0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1ef00 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1ef10 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
1ef20 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
1ef30 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
1ef40 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65  location X to be
1ef50 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1ef60 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20  s..** ^If the X 
1ef70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1ef80 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1ef90 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
1efa0 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
1efb0 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
1efc0 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
1efd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1efe0 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  oc(N)..** ^If th
1eff0 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e N parameter to
1f000 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f010 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72  (X,N) is zero or
1f020 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65  .** negative the
1f030 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1f040 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61  s exactly the sa
1f050 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  me as calling.**
1f060 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29   sqlite3_free(X)
1f070 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65  ..** ^sqlite3_re
1f080 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
1f090 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1f0a0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1f0b0 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1f0c0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1f0d0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e  ze or NULL if in
1f0e0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
1f0f0 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  y is available..
1f100 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1f110 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1f120 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1f130 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1f140 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1f150 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1f160 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1f170 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1f180 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1f190 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1f1a0 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65  loc(X,N) and the
1f1b0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1f1c0 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
1f1d0 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
1f1e0 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20  oc(X,N) returns 
1f1f0 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f  NULL and N is po
1f200 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  sitive, then the
1f210 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  .** prior alloca
1f220 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65  tion is not free
1f230 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
1f240 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
1f250 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20  X,N) interfaces 
1f260 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61  works the same a
1f270 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61  s.** sqlite3_rea
1f280 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74  lloc(X,N) except
1f290 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d   that N is a 64-
1f2a0 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
1f2b0 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
1f2c0 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e  of a 32-bit sign
1f2d0 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  ed integer..**.*
1f2e0 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d  * ^If X is a mem
1f2f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70  ory allocation p
1f300 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
1f310 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1f320 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  malloc(),.** sql
1f330 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1f340 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f350 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  (), or sqlite3_r
1f360 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e  ealloc64(), then
1f370 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1f380 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(X) returns the
1f390 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65   size of that me
1f3a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1f3b0 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68  in bytes..** ^Th
1f3c0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1f3d0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a   by sqlite3_msiz
1f3e0 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61  e(X) might be la
1f3f0 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75  rger than the nu
1f400 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73  mber.** of bytes
1f410 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20   requested when 
1f420 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e  X was allocated.
1f430 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c    ^If X is a NUL
1f440 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a  L pointer then.*
1f450 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28  * sqlite3_msize(
1f460 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  X) returns zero.
1f470 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f    If X points to
1f480 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20   something that 
1f490 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65  is not.** the be
1f4a0 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72  ginning of memor
1f4b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72  y allocation, or
1f4c0 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f   if it points to
1f4d0 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76   a formerly.** v
1f4e0 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  alid memory allo
1f4f0 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20  cation that has 
1f500 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20  now been freed, 
1f510 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1f520 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  r.** of sqlite3_
1f530 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65  msize(X) is unde
1f540 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62  fined and possib
1f550 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
1f560 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65  * ^The memory re
1f570 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1f580 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69  3_malloc(), sqli
1f590 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a  te3_realloc(),.*
1f5a0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1f5b0 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  64(), and sqlite
1f5c0 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a  3_realloc64().**
1f5d0 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1f5e0 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1f5f0 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1f600 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1f610 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1f620 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1f630 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1f640 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1f650 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1f660 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1f670 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1f680 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1f690 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1f6a0 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1f6b0 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1f6c0 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1f6d0 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1f6e0 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1f6f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1f700 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1f710 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1f720 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1f730 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1f740 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1f750 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1f760 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1f770 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
1f780 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
1f790 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
1f7a0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1f7b0 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1f7c0 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
1f7d0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1f7e0 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
1f7f0 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
1f800 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
1f810 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
1f820 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
1f830 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
1f840 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
1f850 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
1f860 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
1f870 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
1f880 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
1f890 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
1f8a0 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
1f8b0 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
1f8c0 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
1f8d0 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1f8e0 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1f8f0 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1f900 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1f910 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1f920 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1f930 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1f940 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1f950 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1f960 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1f970 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1f980 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1f990 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1f9a0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1f9b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f9c0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1f9d0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1f9e0 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1f9f0 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1fa00 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1fa10 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1fa20 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1fa30 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1fa40 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1fa50 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1fa60 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1fa70 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1fa80 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1fa90 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
1faa0 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
1fab0 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
1fac0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c  te3_malloc64(sql
1fad0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f  ite3_uint64);.vo
1fae0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
1faf0 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1fb00 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
1fb10 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20  ealloc64(void*, 
1fb20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b  sqlite3_uint64);
1fb30 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1fb40 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74  ee(void*);.sqlit
1fb50 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  e3_uint64 sqlite
1fb60 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a  3_msize(void*);.
1fb70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1fb80 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f   Memory Allocato
1fb90 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a  r Statistics.**.
1fba0 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64  ** SQLite provid
1fbb0 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74  es these two int
1fbc0 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f  erfaces for repo
1fbd0 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61  rting on the sta
1fbe0 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  tus.** of the [s
1fbf0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1fc00 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
1fc10 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
1fc20 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72  _realloc()].** r
1fc30 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66  outines, which f
1fc40 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  orm the built-in
1fc50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1fc60 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a  on subsystem..**
1fc70 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1fc80 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1fc90 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1fca0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
1fcb0 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  ytes.** of memor
1fcc0 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73  y currently outs
1fcd0 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65  tanding (malloce
1fce0 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29  d but not freed)
1fcf0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
1fd00 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1fd10 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  ter()] routine r
1fd20 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d  eturns the maxim
1fd30 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b  um.** value of [
1fd40 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1fd50 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65  sed()] since the
1fd60 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1fd70 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73  .** was last res
1fd80 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  et.  ^The values
1fd90 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1fda0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1fdb0 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1fdc0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1fdd0 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65  water()] include
1fde0 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a   any overhead.**
1fdf0 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65   added by SQLite
1fe00 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e   in its implemen
1fe10 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  tation of [sqlit
1fe20 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a  e3_malloc()],.**
1fe30 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61   but not overhea
1fe40 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61  d added by the a
1fe50 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79  ny underlying sy
1fe60 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20  stem library.** 
1fe70 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73  routines that [s
1fe80 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1fe90 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a   may call..**.**
1fea0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67   ^The memory hig
1feb0 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
1fec0 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72  reset to the cur
1fed0 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a  rent value of.**
1fee0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1fef0 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20  _used()] if and 
1ff00 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61  only if the para
1ff10 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
1ff20 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1ff30 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65  water()] is true
1ff40 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  .  ^The value re
1ff50 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71  turned.** by [sq
1ff60 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1ff70 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68  hwater(1)] is th
1ff80 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1ff90 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68  k.** prior to th
1ffa0 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69  e reset..*/.sqli
1ffb0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1ffc0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f  3_memory_used(vo
1ffd0 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  id);.sqlite3_int
1ffe0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1fff0 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
20000 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
20010 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
20020 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
20030 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
20040 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
20050 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
20060 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
20070 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
20080 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
20090 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
200a0 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
200b0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
200c0 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
200d0 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
200e0 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
200f0 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
20100 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
20110 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
20120 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
20130 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
20140 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
20150 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
20160 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
20170 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
20180 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
20190 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
201a0 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
201b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
201c0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
201d0 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
201e0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
201f0 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20  to buffer P..** 
20200 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72  ^The P parameter
20210 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70   can be a NULL p
20220 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ointer..**.** ^I
20230 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  f this routine h
20240 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76  as not been prev
20250 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72  iously called or
20260 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
20270 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c  .** call had N l
20280 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20  ess than one or 
20290 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
202a0 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50  or P, then the P
202b0 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64  RNG is.** seeded
202c0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
202d0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
202e0 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
202f0 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65  method of.** the
20300 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
20310 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
20320 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f  * ^If the previo
20330 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
20340 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e  routine had an N
20350 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e   of 1 or more an
20360 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20  d a.** non-NULL 
20370 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64  P then the pseud
20380 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
20390 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
203a0 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
203b0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
203c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
203d0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
203e0 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
203f0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
20400 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
20410 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
20420 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
20430 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
20440 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45   Callbacks.** ME
20450 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
20460 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68   KEYWORDS: {auth
20470 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d  orizer callback}
20480 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
20490 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
204a0 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
204b0 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
204c0 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
204d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
204e0 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
204f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
20500 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
20510 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
20520 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
20530 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
20540 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
20550 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
20560 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
20570 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
20580 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
20590 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
205a0 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69  are_v3()], [sqli
205b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
205c0 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  , [sqlite3_prepa
205d0 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61  re16_v2()],.** a
205e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
205f0 61 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41  are16_v3()].  ^A
20600 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
20610 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
20620 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
20630 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
20640 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
20650 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
20660 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
20670 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20680 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
20690 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
206a0 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
206b0 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
206c0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
206d0 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
206e0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
206f0 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
20700 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
20710 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
20720 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
20730 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
20740 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
20750 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
20760 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
20770 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
20780 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
20790 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
207a0 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
207b0 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
207c0 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
207d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
207e0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
207f0 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
20800 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
20810 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
20820 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
20830 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
20840 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20850 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
20860 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
20870 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
20880 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
20890 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
208a0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
208b0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
208c0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
208d0 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
208e0 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
208f0 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
20900 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
20910 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
20920 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
20930 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
20940 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
20950 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
20960 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
20970 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
20980 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
20990 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
209a0 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
209b0 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
209c0 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
209d0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
209e0 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
209f0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20a00 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
20a10 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
20a20 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
20a30 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
20a40 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
20a50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
20a60 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
20a70 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
20a80 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
20a90 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
20aa0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
20ab0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
20ac0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
20ad0 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
20ae0 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
20af0 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
20b00 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
20b10 61 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20  are either NULL 
20b20 70 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f  pointers or zero
20b30 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
20b40 6e 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74  ngs.** that cont
20b50 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64  ain additional d
20b60 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
20b70 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
20b80 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70  thorized..** App
20b90 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61  lications must a
20ba0 6c 77 61 79 73 20 62 65 20 70 72 65 70 61 72 65  lways be prepare
20bb0 64 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61  d to encounter a
20bc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e   NULL pointer in
20bd0 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74   any.** of the t
20be0 68 69 72 64 20 74 68 72 6f 75 67 68 20 74 68 65  hird through the
20bf0 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
20c00 73 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69  s of the authori
20c10 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e  zation callback.
20c20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
20c30 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
20c40 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61  QLITE_READ].** a
20c50 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
20c60 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
20c70 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
20c80 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
20c90 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65  atement] stateme
20ca0 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65  nt is constructe
20cb0 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a  d to substitute.
20cc0 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20  ** a NULL value 
20cd0 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
20ce0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
20cf0 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20  t would have.** 
20d00 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51  been read if [SQ
20d10 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65  LITE_OK] had bee
20d20 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  n returned.  The
20d30 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
20d40 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62  .** return can b
20d50 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61  e used to deny a
20d60 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72  n untrusted user
20d70 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76   access to indiv
20d80 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73  idual.** columns
20d90 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20   of a table..** 
20da0 5e 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73  ^When a table is
20db0 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 61   referenced by a
20dc0 20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f   [SELECT] but no
20dd0 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61   column values a
20de0 72 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20  re.** extracted 
20df0 66 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20  from that table 
20e00 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20  (for example in 
20e10 61 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20  a query like.** 
20e20 22 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29  "SELECT count(*)
20e30 20 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e   FROM tab") then
20e40 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41   the [SQLITE_REA
20e50 44 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  D] authorizer ca
20e60 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76  llback.** is inv
20e70 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68  oked once for th
20e80 61 74 20 74 61 62 6c 65 20 77 69 74 68 20 61 20  at table with a 
20e90 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74  column name that
20ea0 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72   is an empty str
20eb0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
20ec0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
20ed0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61  SQLITE_DELETE] a
20ee0 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  nd the callback 
20ef0 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
20f00 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
20f10 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65  the [DELETE] ope
20f20 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20  ration proceeds 
20f30 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e  but the.** [trun
20f40 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f  cate optimizatio
20f50 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61  n] is disabled a
20f60 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20  nd all rows are 
20f70 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75  deleted individu
20f80 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  ally..**.** An a
20f90 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65  uthorizer is use
20fa0 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
20fb0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
20fc0 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ing].** SQL stat
20fd0 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75  ements from an u
20fe0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c  ntrusted source,
20ff0 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20   to ensure that 
21000 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
21010 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79  ts.** do not try
21020 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20   to access data 
21030 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c  they are not all
21040 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20  owed to see, or 
21050 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
21060 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75  .** try to execu
21070 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61  te malicious sta
21080 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d  tements that dam
21090 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  age the database
210a0 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c  .  For.** exampl
210b0 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
210c0 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73  n may allow a us
210d0 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69  er to enter arbi
210e0 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65  trary.** SQL que
210f0 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74  ries for evaluat
21100 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73  ion by a databas
21110 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c  e.  But the appl
21120 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20  ication does.** 
21130 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65  not want the use
21140 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20  r to be able to 
21150 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63  make arbitrary c
21160 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a  hanges to the.**
21170 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61   database.  An a
21180 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20  uthorizer could 
21190 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70  then be put in p
211a0 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a  lace while the.*
211b0 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  * user-entered S
211c0 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c  QL is being [sql
211d0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
211e0 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a  repared] that.**
211f0 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79   disallows every
21200 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45  thing except [SE
21210 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73  LECT] statements
21220 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
21230 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74  ions that need t
21240 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72  o process SQL fr
21250 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  om untrusted sou
21260 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c  rces.** might al
21270 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65  so consider lowe
21280 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69  ring resource li
21290 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69  mits using [sqli
212a0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
212b0 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74  and limiting dat
212c0 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67  abase size using
212d0 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63   the [max_page_c
212e0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a  ount] [PRAGMA].*
212f0 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  * in addition to
21300 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72   using an author
21310 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  izer..**.** ^(On
21320 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68  ly a single auth
21330 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e  orizer can be in
21340 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61   place on a data
21350 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
21360 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45  ** at a time.  E
21370 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ach call to sqli
21380 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
21390 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65  er overrides the
213a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c  .** previous cal
213b0 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74  l.)^  ^Disable t
213c0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79  he authorizer by
213d0 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55   installing a NU
213e0 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  LL callback..** 
213f0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69  The authorizer i
21400 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
21410 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fault..**.** The
21420 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21430 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
21440 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
21450 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
21460 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
21470 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
21480 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ed the authorize
21490 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e  r callback..** N
214a0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
214b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
214c0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
214d0 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
214e0 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
214f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
21500 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
21510 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
21520 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
21530 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74  .** ^When [sqlit
21540 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
21550 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70   is used to prep
21560 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  are a statement,
21570 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
21580 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72  t might be re-pr
21590 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73  epared during [s
215a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64  qlite3_step()] d
215b0 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65  ue to a .** sche
215c0 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63  ma change.  Henc
215d0 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  e, the applicati
215e0 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65  on should ensure
215f0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72   that the.** cor
21600 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20  rect authorizer 
21610 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73  callback remains
21620 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67   in place during
21630 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
21640 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  ep()]..**.** ^No
21650 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68  te that the auth
21660 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21670 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20  is invoked only 
21680 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  during.** [sqlit
21690 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
216a0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20   its variants.  
216b0 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73  Authorization is
216c0 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65   not.** performe
216d0 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65  d during stateme
216e0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e  nt evaluation in
216f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21700 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20  ], unless.** as 
21710 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72  stated in the pr
21720 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
21730 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
21740 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69   invokes.** sqli
21750 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
21760 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20   to reprepare a 
21770 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
21780 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  a schema change.
21790 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
217a0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
217b0 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
217c0 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
217d0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
217e0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
217f0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
21800 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
21810 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
21820 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
21830 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
21840 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
21850 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21860 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
21870 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
21880 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
21890 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
218a0 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
218b0 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
218c0 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
218d0 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
218e0 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
218f0 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
21900 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
21910 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
21920 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
21930 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
21940 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
21950 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
21960 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
21970 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
21980 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
21990 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66   used as a [conf
219a0 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  lict resolution 
219b0 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65  mode].** returne
219c0 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  d from the [sqli
219d0 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
219e0 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
219f0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
21a00 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
21a10 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
21a20 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
21a30 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
21a40 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
21a50 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
21a60 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
21a70 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
21a80 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
21a90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
21aa0 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
21ab0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
21ac0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21ad0 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
21ae0 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
21af0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
21b00 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
21b10 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
21b20 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
21b30 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
21b40 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
21b50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
21b60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
21b70 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
21b80 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
21b90 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
21ba0 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
21bb0 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
21bc0 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
21bd0 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
21be0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21bf0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
21c00 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
21c10 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
21c20 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
21c30 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
21c40 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
21c50 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
21c60 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
21c70 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
21c80 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
21c90 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
21ca0 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
21cb0 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
21cc0 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
21cd0 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
21ce0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
21cf0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
21d00 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
21d10 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
21d20 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21d30 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
21d40 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
21d50 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
21d60 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
21d70 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
21d80 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
21d90 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21da0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
21db0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
21dc0 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
21dd0 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
21de0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
21df0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
21e00 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
21e10 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
21e20 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
21e30 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
21e40 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
21e50 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
21e60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21e70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
21e80 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
21e90 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
21ea0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21eb0 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
21ec0 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
21ed0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
21ee0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21f00 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
21f10 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
21f20 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
21f30 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21f40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
21f50 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
21f60 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
21f70 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
21f80 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21fa0 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
21fb0 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
21fc0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21fd0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21ff0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
22000 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
22010 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
22020 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22030 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22040 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
22050 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
22060 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
22070 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22080 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22090 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
220a0 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
220b0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
220c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
220d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
220e0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
220f0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
22100 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22110 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22120 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
22130 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
22140 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22150 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22160 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22170 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
22180 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
22190 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
221a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
221b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
221c0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
221d0 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
221e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
221f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22200 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22210 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
22220 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
22230 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
22240 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22250 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22260 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
22270 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
22280 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22290 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
222a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
222b0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
222c0 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
222d0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
222e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
222f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22300 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
22310 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
22320 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
22330 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22340 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22350 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
22360 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
22370 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
22380 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22390 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
223a0 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
223b0 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
223c0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
223d0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
223e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
223f0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
22400 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
22410 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22420 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22430 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
22440 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
22450 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
22460 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
22470 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
22480 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
22490 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
224a0 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
224b0 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
224c0 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
224d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
224e0 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
224f0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
22500 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
22510 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22520 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
22530 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
22540 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
22550 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
22560 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22570 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
22580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
22590 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
225a0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
225b0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
225c0 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
225d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
225e0 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
225f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22600 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22610 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
22620 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
22630 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
22640 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
22650 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22660 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
22670 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
22680 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
22690 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
226a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
226b0 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
226c0 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
226d0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
226e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
226f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22700 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
22710 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
22720 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22730 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22740 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22750 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
22760 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
22770 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22780 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
22790 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
227a0 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
227b0 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
227c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
227d0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
227e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
227f0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
22800 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
22810 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
22820 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
22830 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22840 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
22850 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
22860 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
22870 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
22880 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22890 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
228a0 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
228b0 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23  longer used */.#
228c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
228d0 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20  CURSIVE         
228e0 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20     33   /* NULL 
228f0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
22900 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f             */../
22910 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
22920 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
22930 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
22940 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
22950 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  3.**.** These ro
22960 75 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65  utines are depre
22970 63 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b  cated. Use the [
22980 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
22990 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
229a0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
229b0 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62  routines describ
229c0 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54  ed here..**.** T
229d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
229e0 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
229f0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
22a00 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
22a10 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
22a20 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
22a30 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
22a40 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
22a50 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
22a60 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
22a70 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
22a80 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
22a90 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
22aa0 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
22ab0 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
22ac0 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
22ad0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
22ae0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
22af0 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
22b00 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
22b10 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
22b20 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
22b30 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
22b40 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
22b50 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
22b60 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
22b70 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
22b80 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
22b90 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
22ba0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
22bb0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
22bc0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
22bd0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
22be0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
22bf0 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
22c00 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
22c10 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
22c20 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
22c30 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
22c40 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
22c50 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
22c60 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20  sed to limit.** 
22c70 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62  the length of [b
22c80 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20  ound parameter] 
22c90 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65  expansion in the
22ca0 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74   output of sqlit
22cb0 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a  e3_trace()..**.*
22cc0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
22cd0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
22ce0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
22cf0 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
22d00 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
22d10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
22d20 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
22d30 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
22d40 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
22d50 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
22d60 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
22d70 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
22d80 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
22d90 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
22da0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
22db0 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
22dc0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
22dd0 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
22de0 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
22df0 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
22e00 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
22e10 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
22e20 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
22e30 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
22e40 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
22e50 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
22e60 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
22e70 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
22e80 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
22e90 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
22ea0 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
22eb0 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
22ec0 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
22ed0 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
22ee0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
22ef0 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
22f00 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
22f10 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
22f20 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
22f30 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
22f40 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
22f50 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45  te..*/.SQLITE_DE
22f60 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73  PRECATED void *s
22f70 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
22f80 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
22f90 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
22fa0 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
22fb0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
22fc0 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69  CATED void *sqli
22fd0 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
22fe0 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
22ff0 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
23000 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
23010 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
23020 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
23030 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45  REF: SQL Trace E
23040 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  vent Codes.** KE
23050 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
23060 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  RACE.**.** These
23070 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74   constants ident
23080 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65  ify classes of e
23090 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62  vents that can b
230a0 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75  e monitored.** u
230b0 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  sing the [sqlite
230c0 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72  3_trace_v2()] tr
230d0 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68  acing logic.  Th
230e0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
230f0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
23100 74 72 61 63 65 5f 76 32 28 29 5d 20 69 73 20 61  trace_v2()] is a
23110 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74  n OR-ed combinat
23120 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ion of one or mo
23130 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  re of.** the fol
23140 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
23150 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  .  ^The first ar
23160 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72  gument to the tr
23170 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
23180 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  is one of the fo
23190 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74  llowing constant
231a0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61  s..**.** New tra
231b0 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d  cing constants m
231c0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
231d0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
231e0 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63  **.** ^A trace c
231f0 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72  allback has four
23200 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c   arguments: xCal
23210 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a  lback(T,C,P,X)..
23220 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65  ** ^The T argume
23230 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  nt is one of the
23240 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f   integer type co
23250 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54  des above..** ^T
23260 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73  he C argument is
23270 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63   a copy of the c
23280 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70  ontext pointer p
23290 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a  assed in as the.
232a0 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  ** fourth argume
232b0 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  nt to [sqlite3_t
232c0 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54  race_v2()]..** T
232d0 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d  he P and X argum
232e0 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72  ents are pointer
232f0 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73  s whose meanings
23300 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a   depend on T..**
23310 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
23320 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d  LITE_TRACE_STMT]
23330 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
23340 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20  CE_STMT</dt>.** 
23350 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
23360 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61  RACE_STMT callba
23370 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68  ck is invoked wh
23380 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74  en a prepared st
23390 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74  atement.** first
233a0 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20   begins running 
233b0 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20  and possibly at 
233c0 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69  other times duri
233d0 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74  ng the.** execut
233e0 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61  ion of the prepa
233f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73  red statement, s
23400 75 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74  uch as at the st
23410 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74  art of each.** t
23420 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61  rigger subprogra
23430 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  m. ^The P argume
23440 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
23450 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  to the.** [prepa
23460 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
23470 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20  ^The X argument 
23480 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
23490 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a  a string which.*
234a0 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e  * is the unexpan
234b0 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20  ded SQL text of 
234c0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
234d0 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c  tement or an SQL
234e0 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61   comment .** tha
234f0 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20  t indicates the 
23500 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20  invocation of a 
23510 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63  trigger.  ^The c
23520 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70  allback can comp
23530 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ute.** the same 
23540 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20  text that would 
23550 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e  have been return
23560 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79  ed by the legacy
23570 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
23580 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
23590 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61  by using the X a
235a0 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62  rgument when X b
235b0 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20  egins with "--" 
235c0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20  and invoking.** 
235d0 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  [sqlite3_expande
235e0 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77  d_sql(P)] otherw
235f0 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ise..**.** [[SQL
23600 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
23610 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54  E]] <dt>SQLITE_T
23620 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74  RACE_PROFILE</dt
23630 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
23640 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
23650 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69  E callback provi
23660 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c  des approximatel
23670 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e  y the same.** in
23680 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20  formation as is 
23690 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
236a0 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  [sqlite3_profile
236b0 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ()] callback..**
236c0 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
236d0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
236e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
236f0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68  tatement] and th
23700 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20  e.** X argument 
23710 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62  points to a 64-b
23720 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  it integer which
23730 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65   is the estimate
23740 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  d of.** the numb
23750 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64  er of nanosecond
23760 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72   that the prepar
23770 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  ed statement too
23780 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68  k to run..** ^Th
23790 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  e SQLITE_TRACE_P
237a0 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20  ROFILE callback 
237b0 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
237c0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
237d0 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  nishes..**.** [[
237e0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57  SQLITE_TRACE_ROW
237f0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
23800 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20  ACE_ROW</dt>.** 
23810 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
23820 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63  RACE_ROW callbac
23830 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
23840 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64  never a prepared
23850 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65  .** statement ge
23860 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65  nerates a single
23870 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20   row of result. 
23880 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75   .** ^The P argu
23890 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
238a0 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  r to the [prepar
238b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
238c0 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d  d the.** X argum
238d0 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a  ent is unused..*
238e0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
238f0 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e  ACE_CLOSE]] <dt>
23900 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f  SQLITE_TRACE_CLO
23910 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  SE</dt>.** <dd>^
23920 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
23930 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69  CLOSE callback i
23940 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
23950 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
23960 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a  nection closes..
23970 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65  ** ^The P argume
23980 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
23990 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  to the [database
239a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a   connection] obj
239b0 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58  ect.** and the X
239c0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75   argument is unu
239d0 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  sed..** </dl>.*/
239e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
239f0 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20  TRACE_STMT      
23a00 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51   0x01.#define SQ
23a10 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
23a20 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69  LE    0x02.#defi
23a30 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
23a40 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a  ROW        0x04.
23a50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
23a60 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20  RACE_CLOSE      
23a70 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0x08../*.** CAPI
23a80 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20  3REF: SQL Trace 
23a90 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  Hook.** METHOD: 
23aa0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
23ab0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
23ac0 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74  _v2(D,M,X,P) int
23ad0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
23ae0 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63   a trace callbac
23af0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
23b00 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73  against [databas
23b10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
23b20 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20   using property 
23b30 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f  mask M.** and co
23b40 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e  ntext pointer P.
23b50 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c    ^If the X call
23b60 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20  back is.** NULL 
23b70 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b  or if the M mask
23b80 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74   is zero, then t
23b90 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c  racing is disabl
23ba0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72  ed.  The.** M ar
23bb0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
23bc0 20 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d   the bitwise OR-
23bd0 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
23be0 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  f.** zero or mor
23bf0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d  e [SQLITE_TRACE]
23c00 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a   constants..**.*
23c10 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  * ^Each call to 
23c20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74  either sqlite3_t
23c30 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
23c40 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65  3_trace_v2() ove
23c50 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63  rrides .** (canc
23c60 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63  els) any prior c
23c70 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
23c80 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74  trace() or sqlit
23c90 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a  e3_trace_v2()..*
23ca0 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c  *.** ^The X call
23cb0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
23cc0 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20  whenever any of 
23cd0 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74  the events ident
23ce0 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73  ified by .** mas
23cf0 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65  k M occur.  ^The
23d00 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20   integer return 
23d10 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63  value from the c
23d20 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65  allback is curre
23d30 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c  ntly.** ignored,
23d40 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79   though this may
23d50 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
23d60 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c  e releases.  Cal
23d70 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lback.** impleme
23d80 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
23d90 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65  return zero to e
23da0 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d  nsure future com
23db0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
23dc0 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62  * ^A trace callb
23dd0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23de0 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e  ith four argumen
23df0 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43  ts: callback(T,C
23e00 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54  ,P,X)..** ^The T
23e10 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
23e20 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
23e30 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61  TRACE].** consta
23e40 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20  nts to indicate 
23e50 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  why the callback
23e60 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a   was invoked..**
23e70 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74   ^The C argument
23e80 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
23e90 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65  e context pointe
23ea0 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20  r..** The P and 
23eb0 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20  X arguments are 
23ec0 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d  pointers whose m
23ed0 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f  eanings depend o
23ee0 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  n T..**.** The s
23ef0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23f00 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
23f10 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61  ntended to repla
23f20 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ce the legacy.**
23f30 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
23f40 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e  ite3_trace()] an
23f50 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d [sqlite3_profi
23f60 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77  le()], both of w
23f70 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72  hich.** are depr
23f80 65 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  ecated..*/.int s
23f90 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
23fa0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75  .  sqlite3*,.  u
23fb0 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20  nsigned uMask,. 
23fc0 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29   int(*xCallback)
23fd0 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c  (unsigned,void*,
23fe0 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20  void*,void*),.  
23ff0 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f  void *pCtx.);../
24000 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
24010 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
24020 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
24030 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
24040 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
24050 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
24060 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
24070 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
24080 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
24090 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
240a0 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
240b0 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
240c0 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
240d0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
240e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
240f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
24100 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
24110 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
24120 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
24130 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
24140 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
24150 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
24160 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
24170 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
24180 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
24190 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
241a0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
241b0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
241c0 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
241d0 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
241e0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
241f0 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61  is the approxima
24200 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  te number of .**
24210 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e   [virtual machin
24220 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20  e instructions] 
24230 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74  that are evaluat
24240 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65  ed between succe
24250 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  ssive.** invocat
24260 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c  ions of the call
24270 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69  back X.  ^If N i
24280 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  s less than one 
24290 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73  then the progres
242a0 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20  s.** handler is 
242b0 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
242c0 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
242d0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
242e0 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
242f0 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
24300 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
24310 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
24320 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
24330 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
24340 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
24350 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
24360 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
24370 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
24380 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
24390 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
243a0 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
243b0 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
243c0 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
243d0 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
243e0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
243f0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
24400 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
24410 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
24420 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
24430 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
24440 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
24450 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
24460 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
24470 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
24480 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
24490 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
244a0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
244b0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
244c0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
244d0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
244e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
244f0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
24500 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
24510 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
24520 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24530 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
24540 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
24550 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
24560 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
24570 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
24580 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
24590 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
245a0 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
245b0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
245c0 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
245d0 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
245e0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
245f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24600 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
24610 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
24620 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  on.** CONSTRUCTO
24630 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
24640 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
24650 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
24660 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
24670 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
24680 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
24690 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
246a0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
246b0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
246c0 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
246d0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
246e0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
246f0 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
24700 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
24710 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
24720 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
24730 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
24740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
24750 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
24760 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
24770 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
24780 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
24790 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
247a0 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
247b0 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
247c0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
247d0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
247e0 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
247f0 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
24800 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
24810 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
24820 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
24830 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
24840 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
24850 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
24860 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
24870 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
24880 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
24890 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
248a0 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
248b0 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
248c0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
248d0 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
248e0 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
248f0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
24900 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
24910 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
24920 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
24930 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
24940 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
24950 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
24960 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
24970 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
24980 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
24990 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
249a0 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c  ult encoding wil
249b0 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64  l be UTF-8 for d
249c0 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64  atabases created
249d0 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65   using.** sqlite
249e0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
249f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
24a00 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
24a10 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61  oding for databa
24a20 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75  ses.** created u
24a30 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  sing sqlite3_ope
24a40 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54  n16() will be UT
24a50 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
24a60 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
24a70 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
24a80 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
24a90 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
24aa0 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
24ab0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
24ac0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
24ad0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
24ae0 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
24af0 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
24b00 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
24b10 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
24b20 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
24b30 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
24b40 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
24b50 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
24b60 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
24b70 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
24b80 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
24b90 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
24ba0 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
24bb0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
24bc0 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
24bd0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
24be0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
24bf0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
24c00 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
24c10 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
24c20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
24c30 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
24c40 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
24c50 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
24c60 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
24c70 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
24c80 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
24c90 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
24ca0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
24cb0 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
24cc0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
24cd0 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
24ce0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
24cf0 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
24d00 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
24d10 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
24d20 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
24d30 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24d40 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
24d50 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
24d60 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
24d70 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
24d80 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
24d90 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
24da0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
24db0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
24dc0 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
24dd0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
24de0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
24df0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
24e00 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
24e10 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
24e20 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
24e30 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
24e40 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
24e50 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
24e60 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
24e70 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
24e80 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
24e90 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
24ea0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
24eb0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
24ec0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
24ed0 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
24ee0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
24ef0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
24f00 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
24f10 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
24f20 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
24f30 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
24f40 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
24f50 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
24f60 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
24f70 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
24f80 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
24f90 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
24fa0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
24fb0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
24fc0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
24fd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
24fe0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24ff0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
25000 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
25010 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
25020 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
25030 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
25040 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
25050 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
25060 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
25070 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
25080 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
25090 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
250a0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
250b0 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
250c0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
250d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
250e0 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
250f0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
25100 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
25110 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
25120 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
25130 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
25140 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
25150 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
25160 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
25170 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
25180 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
25190 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
251a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
251b0 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
251c0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
251d0 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
251e0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
251f0 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
25200 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
25210 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
25220 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
25230 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
25240 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
25250 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
25260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
25270 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
25280 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
25290 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
252a0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
252b0 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
252c0 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
252d0 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
252e0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
252f0 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
25300 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
25310 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
25320 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
25330 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25340 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
25350 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
25360 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
25370 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
25380 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
25390 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
253a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
253b0 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
253c0 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
253d0 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
253e0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
253f0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
25400 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
25410 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
25420 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25430 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
25440 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
25450 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
25460 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
25470 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
25480 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
25490 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
254a0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
254b0 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
254c0 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
254d0 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
254e0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
254f0 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
25500 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
25510 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
25520 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
25530 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
25540 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
25550 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
25560 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
25570 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
25580 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
25590 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
255a0 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
255b0 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
255c0 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
255d0 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
255e0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
255f0 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
25600 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
25610 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
25620 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
25630 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
25640 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
25650 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
25660 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
25670 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
25680 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
25690 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
256a0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
256b0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
256c0 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
256d0 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
256e0 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
256f0 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
25700 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
25710 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
25720 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
25730 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
25740 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
25750 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
25760 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
25770 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
25780 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
25790 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
257a0 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
257b0 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
257c0 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
257d0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
257e0 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
257f0 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
25800 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
25810 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
25820 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
25830 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
25840 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
25850 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
25860 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
25870 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
25880 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
25890 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
258a0 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
258b0 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
258c0 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
258d0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
258e0 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
258f0 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
25900 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
25910 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
25920 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
25930 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
25940 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
25950 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
25960 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
25970 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
25980 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
25990 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
259a0 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
259b0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
259c0 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
259d0 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
259e0 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
259f0 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
25a00 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
25a10 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
25a20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
25a30 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
25a40 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
25a50 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
25a60 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
25a70 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
25a80 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
25a90 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
25aa0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
25ab0 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
25ac0 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
25ad0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
25ae0 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
25af0 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
25b00 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
25b10 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
25b20 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
25b30 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
25b40 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
25b50 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
25b60 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
25b70 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
25b80 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
25b90 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
25ba0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
25bb0 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
25bc0 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
25bd0 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
25be0 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
25bf0 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
25c00 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
25c10 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
25c20 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
25c30 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
25c40 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
25c50 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
25c60 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
25c70 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
25c80 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
25c90 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
25ca0 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
25cb0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
25cc0 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
25cd0 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f  . .** ^(On windo
25ce0 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
25cf0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
25d00 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
25d10 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
25d20 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
25d30 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  C:").)^.**.** [[
25d40 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
25d50 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
25d60 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
25d70 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
25d80 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
25d90 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
25da0 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
25db0 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
25dc0 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
25dd0 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
25de0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
25df0 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73  * SQLite and its
25e00 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73   built-in [VFSes
25e10 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  ] interpret the.
25e20 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65  ** following que
25e30 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
25e40 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
25e50 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
25e60 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
25e70 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
25e80 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
25e90 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
25ea0 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
25eb0 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
25ec0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
25ed0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
25ee0 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
25ef0 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
25f00 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
25f10 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
25f20 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
25f30 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
25f40 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
25f50 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
25f60 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
25f70 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
25f80 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
25f90 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
25fa0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
25fb0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
25fc0 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
25fd0 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
25fe0 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
25ff0 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
26000 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
26010 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
26020 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
26030 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
26040 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
26050 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
26060 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
26070 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
26080 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
26090 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
260a0 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a  r "ro", "rw",.**
260b0 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22       "rwc", or "
260c0 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74  memory". Attempt
260d0 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
260e0 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
260f0 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72   is.**     an er
26100 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
26110 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
26120 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
26130 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
26140 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
26150 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
26160 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
26170 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
26180 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
26190 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
261a0 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
261b0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
261c0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20  _open_v2(). ^If 
261d0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
261e0 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
261f0 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
26200 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
26210 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
26220 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
26230 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
26240 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
26250 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
26260 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
26270 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
26280 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
26290 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
262a0 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
262b0 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
262c0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
262d0 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
262e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
262f0 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64  TE.  ^If the mod
26300 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  e option is.**  
26310 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72     set to "memor
26320 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b  y" then a pure [
26330 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
26340 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72  se] that never r
26350 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77  eads.**     or w
26360 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20  rites from disk 
26370 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20  is used. ^It is 
26380 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
26390 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a  ify a value for.
263a0 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20  **     the mode 
263b0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
263c0 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69  s less restricti
263d0 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65  ve than that spe
263e0 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
263f0 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
26400 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  d in the third p
26410 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
26420 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
26430 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63  *.**   <li> <b>c
26440 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63  ache</b>: ^The c
26450 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d  ache parameter m
26460 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
26470 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a  her "shared" or.
26480 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22  **     "private"
26490 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f  . ^Setting it to
264a0 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75   "shared" is equ
264b0 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
264c0 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51  ng the.**     SQ
264d0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
264e0 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65  CACHE bit in the
264f0 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
26500 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  passed to.**    
26510 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
26520 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65  (). ^Setting the
26530 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
26540 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73   to "private" is
26550 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c   .**     equival
26560 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
26570 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  he SQLITE_OPEN_P
26580 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e  RIVATECACHE bit.
26590 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69  .**     ^If sqli
265a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
265b0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63   used and the "c
265c0 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20  ache" parameter 
265d0 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a  is present in.**
265e0 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e       a URI filen
265f0 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f  ame, its value o
26600 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68  verrides any beh
26610 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20  avior requested 
26620 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
26630 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
26640 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
26650 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
26660 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a  CACHE flag..**.*
26670 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c  *  <li> <b>psow<
26680 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70  /b>: ^The psow p
26690 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74  arameter indicat
266a0 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  es whether or no
266b0 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f  t the.**     [po
266c0 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74  wersafe overwrit
266d0 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73  e] property does
266e0 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70   or does not app
266f0 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ly to the.**    
26700 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f   storage media o
26710 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61  n which the data
26720 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65  base file reside
26730 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  s..**.**  <li> <
26740 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54  b>nolock</b>: ^T
26750 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65  he nolock parame
26760 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
26770 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
26780 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66  .**     which if
26790 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69   set disables fi
267a0 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f  le locking in ro
267b0 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d  llback journal m
267c0 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20  odes.  This.**  
267d0 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72     is useful for
267e0 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74   accessing a dat
267f0 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73  abase on a files
26800 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20  ystem that does 
26810 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f  not.**     suppo
26820 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75  rt locking.  Cau
26830 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20  tion:  Database 
26840 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74  corruption might
26850 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a   result if two.*
26860 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72  *     or more pr
26870 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f  ocesses write to
26880 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
26890 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f  se and any one o
268a0 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70  f those.**     p
268b0 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f  rocesses uses no
268c0 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c  lock=1..**.**  <
268d0 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65  li> <b>immutable
268e0 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74  </b>: ^The immut
268f0 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69  able parameter i
26900 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
26910 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74  y.**     paramet
26920 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  er that indicate
26930 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
26940 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72  ase file is stor
26950 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61  ed on.**     rea
26960 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e  d-only media.  ^
26970 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69  When immutable i
26980 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73  s set, SQLite as
26990 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
269a0 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66  *     database f
269b0 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  ile cannot be ch
269c0 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61  anged, even by a
269d0 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69   process with hi
269e0 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76  gher.**     priv
269f0 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68  ilege, and so th
26a00 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
26a10 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61  ened read-only a
26a20 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a  nd all locking.*
26a30 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65  *     and change
26a40 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69   detection is di
26a50 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e  sabled.  Caution
26a60 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d  : Setting the im
26a70 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70  mutable.**     p
26a80 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74  roperty on a dat
26a90 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20  abase file that 
26aa0 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61  does in fact cha
26ab0 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a  nge can result.*
26ac0 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65  *     in incorre
26ad0 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  ct query results
26ae0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
26af0 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e  CORRUPT] errors.
26b00 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f  .**     See also
26b10 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  : [SQLITE_IOCAP_
26b20 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20  IMMUTABLE]..**  
26b30 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a       .** </ul>.*
26b40 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
26b50 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
26b60 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
26b70 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
26b80 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
26b90 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
26ba0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
26bb0 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
26bc0 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
26bd0 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
26be0 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
26bf0 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
26c00 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
26c10 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
26c20 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
26c30 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
26c40 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
26c50 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
26c60 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
26c70 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
26c80 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
26c90 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
26ca0 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
26cb0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
26cc0 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
26cd0 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
26ce0 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
26cf0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26d00 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
26d10 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
26d20 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
26d30 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
26d40 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
26d50 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
26d60 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
26d70 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26d80 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
26d90 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
26da0 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
26db0 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
26dc0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
26dd0 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
26de0 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
26df0 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
26e00 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
26e10 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
26e20 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
26e30 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
26e40 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
26e50 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
26e60 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
26e70 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
26e80 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
26e90 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
26ea0 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
26eb0 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
26ec0 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
26ed0 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
26ee0 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
26ef0 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
26f00 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
26f10 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
26f20 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
26f30 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
26f40 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
26f50 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
26f60 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
26f70 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
26f80 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
26f90 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
26fa0 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
26fb0 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
26fc0 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
26fd0 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
26fe0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
26ff0 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
27000 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
27010 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
27020 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
27030 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
27040 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
27050 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
27060 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
27070 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
27080 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
27090 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
270a0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
270b0 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
270c0 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
270d0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
270e0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
270f0 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65  vfs=unix-dotfile
27100 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
27110 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
27120 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
27130 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
27140 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66  l VFS "unix-dotf
27150 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20  ile".**         
27160 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66   that uses dot-f
27170 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66  iles in place of
27180 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20   posix advisory 
27190 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e  locking..** <tr>
271a0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
271b0 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
271c0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
271d0 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
271e0 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
271f0 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
27200 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
27210 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
27220 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
27230 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
27240 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
27250 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
27260 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
27270 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
27280 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
27290 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
272a0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
272b0 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
272c0 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
272d0 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
272e0 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
272f0 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
27300 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
27310 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
27320 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
27330 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
27340 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
27350 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
27360 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
27370 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
27380 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
27390 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
273a0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
273b0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
273c0 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
273d0 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
273e0 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
273f0 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
27400 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
27410 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
27420 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
27430 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
27440 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
27450 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
27460 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
27470 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
27480 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
27490 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
274a0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
274b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
274c0 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
274d0 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
274e0 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
274f0 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
27500 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
27510 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
27520 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
27530 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
27540 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
27550 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
27560 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
27570 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
27580 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
27590 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
275a0 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
275b0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
275c0 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
275d0 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
275e0 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
275f0 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ng sqlite3_open(
27600 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
27610 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69  n_v2().  Otherwi
27620 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
27630 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
27640 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
27650 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
27660 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  may fail..**.** 
27670 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
27680 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
27690 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  y].*/.int sqlite
276a0 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
276b0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
276c0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
276d0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
276e0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
276f0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
27700 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
27710 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
27720 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
27730 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
27740 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
27750 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
27760 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
27770 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
27780 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
27790 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
277a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
277b0 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
277c0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
277d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
277e0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
277f0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
27800 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
27810 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
27820 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
27830 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
27840 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
27850 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
27860 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
27870 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
27880 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
27890 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
278a0 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52  in Values For UR
278b0 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  I Parameters.**.
278c0 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69  ** These are uti
278d0 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75  lity routines, u
278e0 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70  seful to VFS imp
278f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68  lementations, th
27900 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73  at check.** to s
27910 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ee if a database
27920 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20   file was a URI 
27930 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61  that contained a
27940 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20   specific query 
27950 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61  .** parameter, a
27960 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73  nd if so obtains
27970 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
27980 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  at query paramet
27990 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69  er..**.** If F i
279a0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
279b0 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  ilename pointer 
279c0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
279d0 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f  xOpen() method o
279e0 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c  f .** a VFS impl
279f0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20  ementation when 
27a00 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
27a10 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68  ter to xOpen() h
27a20 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f  as one or .** mo
27a30 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
27a40 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b  E_OPEN_URI] or [
27a50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
27a60 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e  _DB] bits set an
27a70 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61  d.** P is the na
27a80 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  me of the query 
27a90 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a  parameter, then.
27aa0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  ** sqlite3_uri_p
27ab0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
27ac0 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
27ad0 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61  of the P.** para
27ae0 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73  meter if it exis
27af0 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ts or a NULL poi
27b00 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e  nter if P does n
27b10 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a  ot appear as a .
27b20 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
27b30 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69  er on F.  If P i
27b40 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65  s a query parame
27b50 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20  ter of F.** has 
27b60 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75  no explicit valu
27b70 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
27b80 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
27b90 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  P) returns.** a 
27ba0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d  pointer to an em
27bb0 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  pty string..**.*
27bc0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
27bd0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
27be0 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73   routine assumes
27bf0 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f   that P is a boo
27c00 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65  lean.** paramete
27c10 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72  r and returns tr
27c20 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20  ue (1) or false 
27c30 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  (0) according to
27c40 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66   the value.** of
27c50 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33   P.  The sqlite3
27c60 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
27c70 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,B) routine retu
27c80 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20  rns true (1) if 
27c90 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
27ca0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
27cb0 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73  P is one of "yes
27cc0 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f  ", "true", or "o
27cd0 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73  n" in any.** cas
27ce0 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  e or if the valu
27cf0 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
27d00 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e  non-zero number.
27d10 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65    The .** sqlite
27d20 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
27d30 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65  P,B) routines re
27d40 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20  turns false (0) 
27d50 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a  if the value of.
27d60 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
27d70 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
27d80 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72  no", "false", or
27d90 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61   "off" in any ca
27da0 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20  se or.** if the 
27db0 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
27dc0 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f  h a numeric zero
27dd0 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61  .  If P is not a
27de0 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
27df0 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74  ter on F or if t
27e00 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
27e10 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20   does not match 
27e20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62  any of the.** ab
27e30 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ove, then sqlite
27e40 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
27e50 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21  P,B) returns (B!
27e60 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  =0)..**.** The s
27e70 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
27e80 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20  (F,P,D) routine 
27e90 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c  converts the val
27ea0 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a  ue of P into a.*
27eb0 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  * 64-bit signed 
27ec0 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75  integer and retu
27ed0 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72  rns that integer
27ee0 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73  , or D if P does
27ef0 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20   not.** exist.  
27f00 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  If the value of 
27f10 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f  P is something o
27f20 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74  ther than an int
27f30 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65  eger, then.** ze
27f40 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
27f50 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61  ** .** If F is a
27f60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
27f70 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
27f80 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
27f90 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a  eturns NULL and.
27fa0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
27fb0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
27fc0 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69  turns B.  If F i
27fd0 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69  s not a NULL poi
27fe0 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e  nter and.** is n
27ff0 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
28000 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e  le pathname poin
28010 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  ter that SQLite 
28020 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
28030 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74  xOpen.** VFS met
28040 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  hod, then the be
28050 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72  havior of this r
28060 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69  outine is undefi
28070 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
28080 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  .** undesirable.
28090 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
280a0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
280b0 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72  meter(const char
280c0 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e   *zFilename, con
280d0 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29  st char *zParam)
280e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72  ;.int sqlite3_ur
280f0 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20  i_boolean(const 
28100 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e  char *zFile, con
28110 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c  st char *zParam,
28120 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a   int bDefault);.
28130 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
28140 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
28150 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e  const char*, con
28160 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
28170 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a  3_int64);.../*.*
28180 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
28190 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
281a0 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ages.** METHOD: 
281b0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49  sqlite3.**.** ^I
281c0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
281d0 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  t sqlite3_* API 
281e0 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20  call associated 
281f0 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61  with .** [databa
28200 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
28210 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68   failed, then th
28220 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
28230 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  e(D) interface.*
28240 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  * returns the nu
28250 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f  meric [result co
28260 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
28270 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
28280 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61  r that.** API ca
28290 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f  ll..** If the mo
282a0 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
282b0 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75  ll was successfu
282c0 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  l,.** then the r
282d0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
282e0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
282f0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
28300 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28310 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
28320 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
28330 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
28340 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
28350 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
28360 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
28370 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
28380 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
28390 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
283a0 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
283b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
283c0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
283d0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
283e0 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
283f0 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
28400 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
28410 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
28420 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
28430 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
28440 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
28450 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
28460 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
28470 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
28480 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
28490 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
284a0 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
284b0 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
284c0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
284d0 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
284e0 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
284f0 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
28500 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
28510 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
28520 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
28530 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
28540 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ons.)^.**.** ^Th
28550 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72  e sqlite3_errstr
28560 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
28570 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68  urns the English
28580 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a  -language text.*
28590 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  * that describes
285a0 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64   the [result cod
285b0 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a  e], as UTF-8..**
285c0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
285d0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
285e0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
285f0 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
28600 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74  .** and must not
28610 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65   be freed by the
28620 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a   application)^..
28630 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73  **.** When the s
28640 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
28650 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e  ding mode] is in
28660 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62   use, it might b
28670 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68  e the.** case th
28680 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f  at a second erro
28690 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65  r occurs on a se
286a0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e  parate thread in
286b0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20   between.** the 
286c0 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73  time of the firs
286d0 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20  t error and the 
286e0 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e  call to these in
286f0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65  terfaces..** Whe
28700 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20  n that happens, 
28710 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  the second error
28720 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65   will be reporte
28730 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a  d since these.**
28740 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61   interfaces alwa
28750 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f  ys report the mo
28760 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74  st recent result
28770 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  .  To avoid.** t
28780 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64  his, each thread
28790 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c   can obtain excl
287a0 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65  usive use of the
287b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
287c0 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69  ction] D.** by i
287d0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
287e0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73  _mutex_enter]([s
287f0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
28800 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69  (D)) before begi
28810 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20  nning.** to use 
28820 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b  D and invoking [
28830 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65  sqlite3_mutex_le
28840 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ave]([sqlite3_db
28850 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65  _mutex](D)) afte
28860 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74  r.** all calls t
28870 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73  o the interfaces
28880 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65   listed here are
28890 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a   completed..**.*
288a0 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63  * If an interfac
288b0 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c  e fails with SQL
288c0 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74  ITE_MISUSE, that
288d0 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72   means the inter
288e0 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f  face.** was invo
288f0 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ked incorrectly 
28900 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
28910 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73  on.  In that cas
28920 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  e, the.** error 
28930 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
28940 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20   may or may not 
28950 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73  be set..*/.int s
28960 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
28970 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
28980 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
28990 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
289a0 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
289b0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
289c0 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
289d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
289e0 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
289f0 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  e3*);.const char
28a00 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72   *sqlite3_errstr
28a10 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
28a20 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 64  PI3REF: Prepared
28a30 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
28a40 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
28a50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28a60 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
28a70 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
28a80 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
28a90 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
28aa0 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
28ab0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
28ac0 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f  t.** has been co
28ad0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61  mpiled into bina
28ae0 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72  ry form and is r
28af0 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75  eady to be evalu
28b00 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  ated..**.** Thin
28b10 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74  k of each SQL st
28b20 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70  atement as a sep
28b30 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70  arate computer p
28b40 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20  rogram.  The.** 
28b50 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
28b60 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  t is source code
28b70 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73 74  .  A prepared st
28b80 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a  atement object .
28b90 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c  ** is the compil
28ba0 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20  ed object code. 
28bb0 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65   All SQL must be
28bc0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
28bd0 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  a.** prepared st
28be0 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69  atement before i
28bf0 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a  t can be run..**
28c00 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63  .** The life-cyc
28c10 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  le of a prepared
28c20 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
28c30 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c  t usually goes l
28c40 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
28c50 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
28c60 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65 64  ate the prepared
28c70 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
28c80 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
28c90 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a  _prepare_v2()]..
28ca0 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
28cb0 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65  ues to [paramete
28cc0 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
28cd0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
28ce0 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
28cf0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
28d00 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
28d10 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
28d20 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
28d30 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
28d40 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
28d50 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
28d60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
28d70 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
28d80 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
28d90 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
28da0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
28db0 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
28dc0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
28dd0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
28de0 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
28df0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
28e00 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
28e10 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
28e20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
28e30 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a  n-time Limits.**
28e40 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
28e50 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e  .**.** ^(This in
28e60 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74  terface allows t
28e70 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f  he size of vario
28e80 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  us constructs to
28e90 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f   be limited.** o
28ea0 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  n a connection b
28eb0 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  y connection bas
28ec0 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  is.  The first p
28ed0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
28ee0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
28ef0 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c  nection] whose l
28f00 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65  imit is to be se
28f10 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54  t or queried.  T
28f20 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
28f30 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66  ameter is one of
28f40 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65   the [limit cate
28f50 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66  gories] that def
28f60 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f  ine a.** class o
28f70 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  f constructs to 
28f80 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e  be size limited.
28f90 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61    The third para
28fa0 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
28fb0 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68  new limit for th
28fc0 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a  at construct.)^.
28fd0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65  **.** ^If the ne
28fe0 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
28ff0 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
29000 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
29010 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65  nged..** ^(For e
29020 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ach limit catego
29030 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ry SQLITE_LIMIT_
29040 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72  <i>NAME</i> ther
29050 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69  e is a .** [limi
29060 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20  ts | hard upper 
29070 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74  bound].** set at
29080 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79   compile-time by
29090 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f   a C preprocesso
290a0 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a  r macro called.*
290b0 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49  * [limits | SQLI
290c0 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f  TE_MAX_<i>NAME</
290d0 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c  i>]..** (The "_L
290e0 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61  IMIT_" in the na
290f0 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f  me is changed to
29100 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20   "_MAX_".))^.** 
29110 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63  ^Attempts to inc
29120 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
29130 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
29140 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
29150 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
29160 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
29170 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a  pper bound..**.*
29180 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66  * ^Regardless of
29190 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
291a0 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68  the limit was ch
291b0 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b  anged, the .** [
291c0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
291d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
291e0 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ns the prior val
291f0 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e  ue of the limit.
29200 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66  .** ^Hence, to f
29210 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  ind the current 
29220 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74  value of a limit
29230 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e   without changin
29240 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20  g it,.** simply 
29250 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65  invoke this inte
29260 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74  rface with the t
29270 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73  hird parameter s
29280 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20  et to -1..**.** 
29290 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
292a0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
292b0 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
292c0 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
292d0 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
292e0 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
292f0 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
29300 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
29310 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
29320 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
29330 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
29340 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
29350 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
29360 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
29370 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
29380 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
29390 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
293a0 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
293b0 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
293c0 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
293d0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
293e0 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
293f0 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
29400 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
29410 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
29420 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
29430 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
29440 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
29450 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
29460 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
29470 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
29480 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
29490 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
294a0 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
294b0 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
294c0 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
294d0 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
294e0 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
294f0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
29500 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
29510 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
29520 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
29530 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
29540 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
29550 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
29560 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
29570 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
29580 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
29590 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
295a0 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
295b0 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
295c0 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
295d0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
295e0 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
295f0 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
29600 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
29610 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
29620 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29630 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
29640 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
29650 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
29660 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
29670 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
29680 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
29690 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
296a0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
296b0 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
296c0 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
296d0 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
296e0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
296f0 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
29700 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
29710 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
29720 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
29730 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
29740 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
29750 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
29760 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
29770 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
29780 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
29790 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
297a0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
297b0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
297c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
297d0 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
297e0 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
297f0 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e  or table row, in
29800 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a   bytes.<dd>)^.**
29810 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29820 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20  IT_SQL_LENGTH]] 
29830 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29840 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
29850 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29860 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
29870 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
29880 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  , in bytes.</dd>
29890 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
298a0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d  E_LIMIT_COLUMN]]
298b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
298c0 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
298d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
298e0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
298f0 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
29900 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
29910 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
29920 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
29930 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
29940 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
29950 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
29960 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
29970 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
29980 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
29990 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
299a0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20  IT_EXPR_DEPTH]] 
299b0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
299c0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
299d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
299e0 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
299f0 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
29a00 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
29a10 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29a20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
29a30 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e  POUND_SELECT]] ^
29a40 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29a50 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
29a60 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
29a70 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
29a80 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
29a90 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
29aa0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
29ab0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29ac0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20  LIMIT_VDBE_OP]] 
29ad0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29ae0 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
29af0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29b00 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
29b10 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
29b20 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
29b30 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
29b40 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
29b50 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  QL statement.  I
29b60 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  f [sqlite3_prepa
29b70 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74  re_v2()] or.** t
29b80 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74 72  he equivalent tr
29b90 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ies to allocate 
29ba0 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20 74  space for more t
29bb0 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f 70  han this many op
29bc0 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69  codes.** in a si
29bd0 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20 73 74  ngle prepared st
29be0 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49  atement, an SQLI
29bf0 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69  TE_NOMEM error i
29c00 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
29c10 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29c20 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
29c30 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  _ARG]] ^(<dt>SQL
29c40 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
29c50 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
29c60 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
29c70 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
29c80 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
29c90 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
29ca0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  [SQLITE_LIMIT_AT
29cb0 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53  TACHED]] ^(<dt>S
29cc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
29cd0 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
29ce0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29cf0 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
29d00 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
29d10 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
29d20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29d30 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
29d40 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  ENGTH]].** ^(<dt
29d50 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
29d60 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
29d70 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
29d80 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
29d90 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
29da0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
29db0 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
29dc0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
29dd0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
29de0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
29df0 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20  BLE_NUMBER]].** 
29e00 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29e10 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
29e20 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
29e30 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
29e40 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
29e50 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
29e60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
29e70 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29e80 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
29e90 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
29ea0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
29eb0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
29ec0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29ed0 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
29ee0 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
29ef0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
29f00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52  SQLITE_LIMIT_WOR
29f10 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28  KER_THREADS]] ^(
29f20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29f30 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c  _WORKER_THREADS<
29f40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29f50 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29f60 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b  f auxiliary work
29f70 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20  er threads that 
29f80 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65  a single.** [pre
29f90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29fa0 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e   may start.</dd>
29fb0 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  )^.** </dl>.*/.#
29fc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29fd0 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  MIT_LENGTH      
29fe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a                0.
29ff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2a000 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20  IMIT_SQL_LENGTH 
2a010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
2a020 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a030 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20  LIMIT_COLUMN    
2a040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a050 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2a060 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
2a070 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
2a080 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
2a090 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
2a0a0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
2a0b0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
2a0c0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
2a0d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a0e0 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
2a0f0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2a100 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20  ON_ARG          
2a110 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
2a120 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
2a130 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  HED             
2a140 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
2a150 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
2a160 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20  _PATTERN_LENGTH 
2a170 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
2a180 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2a190 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20  IABLE_NUMBER    
2a1a0 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
2a1b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52   SQLITE_LIMIT_TR
2a1c0 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20  IGGER_DEPTH     
2a1d0 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e         10.#defin
2a1e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  e SQLITE_LIMIT_W
2a1f0 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20  ORKER_THREADS   
2a200 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a          11../*.*
2a210 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70  * CAPI3REF: Prep
2a220 61 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  are Flags.**.** 
2a230 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
2a240 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 66  define various f
2a250 6c 61 67 73 20 74 68 61 74 20 63 61 6e 20 62 65  lags that can be
2a260 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
2a270 22 70 72 65 70 46 6c 61 67 73 22 20 70 61 72 61  "prepFlags" para
2a280 6d 65 74 65 72 20 6f 66 20 74 68 65 20 5b 73 71  meter of the [sq
2a290 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33  lite3_prepare_v3
2a2a0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
2a2b0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
2a2c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ()] interfaces..
2a2d0 2a 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20  **.** New flags 
2a2e0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
2a2f0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
2a300 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
2a310 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
2a320 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53  E_PREPARE_PERSIS
2a330 54 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  TENT]] ^(<dt>SQL
2a340 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53  ITE_PREPARE_PERS
2a350 49 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  ISTENT</dt>.** <
2a360 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50 52  dd>The SQLITE_PR
2a370 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54  EPARE_PERSISTENT
2a380 20 66 6c 61 67 20 69 73 20 61 20 68 69 6e 74 20   flag is a hint 
2a390 74 6f 20 74 68 65 20 71 75 65 72 79 20 70 6c 61  to the query pla
2a3a0 6e 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  nner.** that the
2a3b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2a3c0 65 6e 74 20 77 69 6c 6c 20 62 65 20 72 65 74 61  ent will be reta
2a3d0 69 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20  ined for a long 
2a3e0 74 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62  time and.** prob
2a3f0 61 62 6c 79 20 72 65 75 73 65 64 20 6d 61 6e 79  ably reused many
2a400 20 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f   times.)^ ^Witho
2a410 75 74 20 74 68 69 73 20 66 6c 61 67 2c 20 5b 73  ut this flag, [s
2a420 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2a430 33 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  3()].** and [sql
2a440 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2a450 33 28 29 5d 20 61 73 73 75 6d 65 20 74 68 61 74  3()] assume that
2a460 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2a470 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a  atement will .**
2a480 20 62 65 20 75 73 65 64 20 6a 75 73 74 20 6f 6e   be used just on
2a490 63 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 61 20  ce or at most a 
2a4a0 66 65 77 20 74 69 6d 65 73 20 61 6e 64 20 74 68  few times and th
2a4b0 65 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73 69  en destroyed usi
2a4c0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
2a4d0 69 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74  inalize()] relat
2a4e0 69 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20  ively soon. The 
2a4f0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
2a500 74 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f  tation acts.** o
2a510 6e 20 74 68 69 73 20 68 69 6e 74 20 62 79 20 61  n this hint by a
2a520 76 6f 69 64 69 6e 67 20 74 68 65 20 75 73 65 20  voiding the use 
2a530 6f 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  of [lookaside me
2a540 6d 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20  mory] so as not 
2a550 74 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20 74 68  to.** deplete th
2a560 65 20 6c 69 6d 69 74 65 64 20 73 74 6f 72 65 20  e limited store 
2a570 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  of lookaside mem
2a580 6f 72 79 2e 20 46 75 74 75 72 65 20 76 65 72 73  ory. Future vers
2a590 69 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ions of.** SQLit
2a5a0 65 20 6d 61 79 20 61 63 74 20 6f 6e 20 74 68 69  e may act on thi
2a5b0 73 20 68 69 6e 74 20 64 69 66 66 65 72 65 6e 74  s hint different
2a5c0 6c 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ly..** </dl>.*/.
2a5d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
2a5e0 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e  REPARE_PERSISTEN
2a5f0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  T              0
2a600 78 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  x01../*.** CAPI3
2a610 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
2a620 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
2a630 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
2a640 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
2a650 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  iler}.** METHOD:
2a660 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53   sqlite3.** CONS
2a670 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
2a680 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  _stmt.**.** To e
2a690 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73 74  xecute an SQL st
2a6a0 61 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74  atement, it must
2a6b0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
2a6c0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
2a6d0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
2a6e0 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
2a6f0 65 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c  e routines.  Or,
2a700 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   in other words,
2a710 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2a720 2a 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63 74  ** are construct
2a730 6f 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72 65  ors for the [pre
2a740 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a750 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54   object..**.** T
2a760 68 65 20 70 72 65 66 65 72 72 65 64 20 72 6f 75  he preferred rou
2a770 74 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20 5b  tine to use is [
2a780 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2a790 76 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b  v2()].  The.** [
2a7a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2a7b0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  )] interface is 
2a7c0 6c 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75 6c  legacy and shoul
2a7d0 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a  d be avoided..**
2a7e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a7f0 65 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20 65  e_v3()] has an e
2a800 78 74 72 61 20 22 70 72 65 70 46 6c 61 67 73 22  xtra "prepFlags"
2a810 20 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73 20   option that is 
2a820 75 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63  used.** for spec
2a830 69 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  ial purposes..**
2a840 0a 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20 74  .** The use of t
2a850 68 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61  he UTF-8 interfa
2a860 63 65 73 20 69 73 20 70 72 65 66 65 72 72 65 64  ces is preferred
2a870 2c 20 61 73 20 53 51 4c 69 74 65 20 63 75 72 72  , as SQLite curr
2a880 65 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c  ently.** does al
2a890 6c 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67 20  l parsing using 
2a8a0 55 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46 2d  UTF-8.  The UTF-
2a8b0 31 36 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  16 interfaces ar
2a8c0 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73  e provided.** as
2a8d0 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20   a convenience. 
2a8e0 20 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65   The UTF-16 inte
2a8f0 72 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20 63  rfaces work by c
2a900 6f 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a  onverting the.**
2a910 20 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74 6f   input text into
2a920 20 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76   UTF-8, then inv
2a930 6f 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65 73  oking the corres
2a940 70 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69 6e  ponding UTF-8 in
2a950 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
2a960 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2a970 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
2a980 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a990 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
2a9a0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
2a9b0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
2a9c0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
2a9d0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
2a9e0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
2a9f0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
2aa00 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
2aa10 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
2aa20 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
2aa30 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
2aa40 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
2aa50 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
2aa60 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
2aa70 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
2aa80 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
2aa90 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
2aaa0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2aab0 72 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72  re(), sqlite3_pr
2aac0 65 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61  epare_v2(),.** a
2aad0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2aae0 72 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v3().** inter
2aaf0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
2ab00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2ab10 70 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74 65  pare16(), sqlite
2ab20 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2ab30 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ,.** and sqlite3
2ab40 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20  _prepare16_v3() 
2ab50 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
2ab60 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
2ab70 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61  argument is nega
2ab80 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20  tive, then zSql 
2ab90 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
2aba0 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
2abb0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
2abc0 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76  nByte is positiv
2abd0 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
2abe0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
2abf0 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
2ac00 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20  Sql.  ^If nByte 
2ac10 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f  is zero, then no
2ac20 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2ac30 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61  tement is genera
2ac40 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ted..** If the c
2ac50 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74  aller knows that
2ac60 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
2ac70 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
2ac80 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  inated, then.** 
2ac90 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
2aca0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
2acb0 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e  antage to passin
2acc0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
2acd0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
2ace0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2acf0 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
2ad00 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
2ad10 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
2ad20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  nul-terminator..
2ad30 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
2ad40 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
2ad50 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
2ad60 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
2ad70 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
2ad80 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
2ad90 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
2ada0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
2adb0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
2adc0 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
2add0 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
2ade0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
2adf0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
2ae00 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
2ae10 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
2ae20 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
2ae30 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
2ae40 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
2ae50 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
2ae60 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2ae70 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
2ae80 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
2ae90 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
2aea0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
2aeb0 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
2aec0 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
2aed0 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
2aee0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
2aef0 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
2af00 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
2af10 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
2af20 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
2af30 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
2af40 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
2af50 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
2af60 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
2af70 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
2af80 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
2af90 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
2afa0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2afb0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
2afc0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
2afd0 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
2afe0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2aff0 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
2b000 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b010 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
2b020 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
2b030 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
2b040 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
2b050 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
2b060 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
2b070 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2b080 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  (), sqlite3_prep
2b090 61 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74 65  are_v3(), sqlite
2b0a0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2b0b0 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ,.** and sqlite3
2b0c0 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20  _prepare16_v3() 
2b0d0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
2b0e0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
2b0f0 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
2b100 0a 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69 6e  .** The older in
2b110 74 65 72 66 61 63 65 73 20 28 73 71 6c 69 74 65  terfaces (sqlite
2b120 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
2b130 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b140 36 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74 61  6()).** are reta
2b150 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
2b160 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
2b170 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
2b180 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
2b190 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22 20  ** ^In the "vX" 
2b1a0 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
2b1b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b1c0 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
2b1d0 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
2b1e0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
2b1f0 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
2b200 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
2b210 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
2b220 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
2b230 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2b240 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
2b250 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
2b260 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
2b270 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
2b280 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
2b290 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
2b2a0 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
2b2b0 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
2b2c0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
2b2d0 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
2b2e0 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
2b2f0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
2b300 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2b310 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
2b320 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
2b330 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
2b340 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61  again. As many a
2b350 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43  s [SQLITE_MAX_SC
2b360 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72  HEMA_RETRY].** r
2b370 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75  etries will occu
2b380 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  r before sqlite3
2b390 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70  _step() gives up
2b3a0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20   and returns an 
2b3b0 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  error..** </li>.
2b3c0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
2b3d0 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
2b3e0 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
2b3f0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
2b400 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
2b410 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
2b420 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
2b430 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
2b440 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
2b450 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
2b460 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2b470 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
2b480 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
2b490 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2b4a0 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
2b4b0 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
2b4c0 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
2b4d0 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
2b4e0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2b4f0 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
2b500 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
2b510 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
2b520 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
2b530 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
2b540 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
2b550 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
2b560 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
2b570 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
2b580 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
2b590 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
2b5a0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
2b5b0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
2b5c0 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
2b5d0 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
2b5e0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
2b5f0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
2b600 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
2b610 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
2b620 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
2b630 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
2b640 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
2b650 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
2b660 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
2b670 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
2b680 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
2b690 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
2b6a0 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
2b6b0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
2b6c0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
2b6d0 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
2b6e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2b6f0 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
2b700 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
2b710 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
2b720 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
2b730 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
2b740 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
2b750 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
2b760 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
2b770 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
2b780 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
2b790 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
2b7a0 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
2b7b0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
2b7c0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2b7d0 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
2b7e0 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
2b7f0 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
2b800 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
2b810 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
2b820 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
2b830 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  d..** </li>.**.*
2b840 2a 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72  * <p>^sqlite3_pr
2b850 65 70 61 72 65 5f 76 33 28 29 20 64 69 66 66 65  epare_v3() diffe
2b860 72 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  rs from sqlite3_
2b870 70 72 65 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c  prepare_v2() onl
2b880 79 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74  y in having.** t
2b890 68 65 20 65 78 74 72 61 20 70 72 65 70 46 6c 61  he extra prepFla
2b8a0 67 73 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68  gs parameter, wh
2b8b0 69 63 68 20 69 73 20 61 20 62 69 74 20 61 72 72  ich is a bit arr
2b8c0 61 79 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66  ay consisting of
2b8d0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65   zero or.** more
2b8e0 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
2b8f0 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45  PREPARE_PERSISTE
2b900 4e 54 7c 53 51 4c 49 54 45 5f 50 52 45 50 41 52  NT|SQLITE_PREPAR
2b910 45 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68  E_*] flags.  ^Th
2b920 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  e.** sqlite3_pre
2b930 70 61 72 65 5f 76 32 28 29 20 69 6e 74 65 72 66  pare_v2() interf
2b940 61 63 65 20 77 6f 72 6b 73 20 65 78 61 63 74 6c  ace works exactl
2b950 79 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a  y the same as.**
2b960 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b970 5f 76 33 28 29 20 77 69 74 68 20 61 20 7a 65 72  _v3() with a zer
2b980 6f 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61  o prepFlags para
2b990 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  meter..** </ol>.
2b9a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
2b9b0 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
2b9c0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2b9d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2b9e0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2b9f0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2ba00 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2ba10 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2ba20 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2ba30 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2ba40 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2ba50 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2ba60 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2ba70 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2ba80 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2ba90 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2baa0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2bab0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2bac0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2bad0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2bae0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2baf0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
2bb00 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2bb10 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2bb20 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2bb30 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
2bb40 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2bb50 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
2bb60 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2bb70 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2bb80 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2bb90 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2bba0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2bbb0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2bbc0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2bbd0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2bbe0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2bbf0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2bc00 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2bc10 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2bc20 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2bc30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2bc40 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v3(.  sqlite3 *d
2bc50 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2bc60 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2bc70 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2bc80 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2bc90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2bca0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2bcb0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2bcc0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2bcd0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2bce0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2bcf0 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  /.  unsigned int
2bd00 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a   prepFlags, /* Z
2bd10 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49  ero or more SQLI
2bd20 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67  TE_PREPARE_ flag
2bd30 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  s */.  sqlite3_s
2bd40 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2bd50 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2bd60 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2bd70 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2bd80 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2bd90 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2bda0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2bdb0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2bdc0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
2bdd0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2bde0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2bdf0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2be00 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2be10 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2be20 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2be30 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2be40 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2be50 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2be60 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2be70 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2be80 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2be90 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2bea0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2beb0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2bec0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2bed0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2bee0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2bef0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2bf00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2bf10 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2bf20 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2bf30 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2bf40 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2bf50 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2bf60 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2bf70 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2bf80 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2bf90 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2bfa0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2bfb0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2bfc0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2bfd0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2bfe0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2bff0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2c000 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2c010 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2c020 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2c030 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2c040 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2c050 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20 20  prepare16_v3(.  
2c060 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2c070 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2c080 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2c090 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
2c0a0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2c0b0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
2c0c0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2c0d0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2c0e0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2c0f0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2c100 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 75  in bytes. */.  u
2c110 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 70  nsigned int prep
2c120 46 61 6c 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f  Falgs, /* Zero o
2c130 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 52  r more SQLITE_PR
2c140 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f 0a  EPARE_ flags */.
2c150 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2c160 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2c170 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2c180 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2c190 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
2c1a0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2c1b0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2c1c0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2c1d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c1e0 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
2c1f0 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54  ement SQL.** MET
2c200 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2c210 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2c220 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65  ite3_sql(P) inte
2c230 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2c240 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70  pointer to a cop
2c250 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a  y of the UTF-8.*
2c260 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
2c270 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61  to create [prepa
2c280 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2c290 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65   if P was.** cre
2c2a0 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ated by [sqlite3
2c2b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2c2c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2c2d0 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v3()],.** [sqli
2c2e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2c2f0 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 33  ()], or [sqlite3
2c300 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 5d  _prepare16_v3()]
2c310 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2c320 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50  3_expanded_sql(P
2c330 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2c340 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2c350 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69   a UTF-8.** stri
2c360 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
2c370 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 72  e SQL text of pr
2c380 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c390 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 6e   P with.** [boun
2c3a0 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 78  d parameters] ex
2c3b0 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  panded..**.** ^(
2c3c0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
2c3d0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2c3e0 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 20  ment is created 
2c3f0 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a 2a  using the SQL.**
2c400 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 61   text "SELECT $a
2c410 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 20  bc,:xyz" and if 
2c420 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 69  parameter $abc i
2c430 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 67  s bound to integ
2c440 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 70  er 2345.** and p
2c450 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 73  arameter :xyz is
2c460 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 73   unbound, then s
2c470 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 6c  qlite3_sql() wil
2c480 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  l return.** the 
2c490 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 2c  original string,
2c4a0 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a 78   "SELECT $abc,:x
2c4b0 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 5f  yz" but sqlite3_
2c4c0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a 2a  expanded_sql().*
2c4d0 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 53  * will return "S
2c4e0 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c 22  ELECT 2345,NULL"
2c4f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
2c500 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2c510 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  sql() interface 
2c520 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20  returns NULL if 
2c530 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
2c540 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c 61  ory.** is availa
2c550 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ble to hold the 
2c560 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 68  result, or if th
2c570 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 65  e result would e
2c580 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 65  xceed the.** the
2c590 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 20   maximum string 
2c5a0 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e 65  length determine
2c5b0 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  d by the [SQLITE
2c5c0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e 0a  _LIMIT_LENGTH]..
2c5d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
2c5e0 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
2c5f0 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
2c600 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 20  e option limits 
2c610 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 62  the size of.** b
2c620 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 65  ound parameter e
2c630 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 65  xpansions.  ^The
2c640 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52   [SQLITE_OMIT_TR
2c650 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
2c660 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 73  e.** option caus
2c670 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e  es sqlite3_expan
2c680 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c 77  ded_sql() to alw
2c690 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c 2e  ays return NULL.
2c6a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69  .**.** ^The stri
2c6b0 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ng returned by s
2c6c0 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 73  qlite3_sql(P) is
2c6d0 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c 69   managed by SQLi
2c6e0 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 74  te and is.** aut
2c6f0 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 64  omatically freed
2c700 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 72   when the prepar
2c710 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2c720 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 54  finalized..** ^T
2c730 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2c740 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 78  ed by sqlite3_ex
2c750 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 6f  panded_sql(P), o
2c760 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e 64  n the other hand
2c770 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 64  ,.** is obtained
2c780 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2c790 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 73  alloc()] and mus
2c7a0 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68 65  t be free by the
2c7b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
2c7c0 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  by passing it to
2c7d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2c7e0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
2c7f0 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
2c800 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2c810 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
2c820 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73  3_expanded_sql(s
2c830 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2c840 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2c850 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
2c860 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
2c870 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
2c880 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f  atabase.** METHO
2c890 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2c8a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c8b0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2c8c0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
2c8d0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
2c8e0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
2c8f0 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
2c900 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c910 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
2c920 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
2c930 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2c940 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2c950 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
2c960 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
2c970 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2c980 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
2c990 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
2c9a0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
2c9b0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
2c9c0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
2c9d0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
2c9e0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
2c9f0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2ca00 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
2ca10 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
2ca20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
2ca30 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
2ca40 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
2ca50 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
2ca60 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
2ca70 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
2ca80 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
2ca90 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2caa0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
2cab0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
2cac0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
2cad0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
2cae0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
2caf0 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
2cb00 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2cb10 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2cb20 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2cb30 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
2cb40 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
2cb50 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
2cb60 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
2cb70 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
2cb80 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
2cb90 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
2cba0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
2cbb0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
2cbc0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
2cbd0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
2cbe0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
2cbf0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2cc00 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
2cc10 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
2cc20 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
2cc30 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
2cc40 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
2cc50 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
2cc60 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
2cc70 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
2cc80 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
2cc90 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
2cca0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
2ccb0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
2ccc0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
2ccd0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
2cce0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
2ccf0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2cd00 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
2cd10 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
2cd20 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
2cd30 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
2cd40 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
2cd50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
2cd60 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
2cd70 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
2cd80 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2cd90 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2cda0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54  s on disk..** ^T
2cdb0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
2cdc0 72 65 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72  readonly() inter
2cdd0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2cde0 65 20 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69  e for [BEGIN] si
2cdf0 6e 63 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d  nce.** [BEGIN] m
2ce00 65 72 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72  erely sets inter
2ce10 6e 61 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74  nal flags, but t
2ce20 68 65 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20  he [BEGIN|BEGIN 
2ce30 49 4d 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a  IMMEDIATE] and.*
2ce40 2a 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45  * [BEGIN|BEGIN E
2ce50 58 43 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e  XCLUSIVE] comman
2ce60 64 73 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20  ds do touch the 
2ce70 64 61 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a  database and so.
2ce80 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
2ce90 72 65 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72  readonly() retur
2cea0 6e 73 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f  ns false for tho
2ceb0 73 65 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a  se commands..*/.
2cec0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
2ced0 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
2cee0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2cef0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cf00 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
2cf10 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2cf20 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
2cf30 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2cf40 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2cf50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2cf60 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66  t_busy(S) interf
2cf70 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2cf80 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
2cf90 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2cfa0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73  statement] S has
2cfb0 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74   been stepped at
2cfc0 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e   least once usin
2cfd0 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  g .** [sqlite3_s
2cfe0 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20  tep(S)] but has 
2cff0 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63  neither run to c
2d000 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72  ompletion (retur
2d010 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  ned.** [SQLITE_D
2d020 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ONE] from [sqlit
2d030 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72  e3_step(S)]) nor
2d040 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
2d050 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
2d060 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
2d070 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2d080 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
2d090 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
2d0a0 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
2d0b0 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
2d0c0 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
2d0d0 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
2d0e0 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
2d0f0 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
2d100 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
2d110 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
2d120 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2d130 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2d140 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
2d150 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
2d160 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
2d170 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
2d180 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
2d190 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
2d1a0 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
2d1b0 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
2d1c0 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
2d1d0 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
2d1e0 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
2d1f0 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
2d200 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
2d210 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
2d220 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
2d230 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
2d240 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
2d250 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
2d260 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
2d270 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
2d280 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e  tion open..*/.in
2d290 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  t sqlite3_stmt_b
2d2a0 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  usy(sqlite3_stmt
2d2b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2d2c0 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
2d2d0 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
2d2e0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
2d2f0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
2d300 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
2d310 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d320 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
2d330 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
2d340 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2d350 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
2d360 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
2d370 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
2d380 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
2d390 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
2d3a0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
2d3b0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
2d3c0 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
2d3d0 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
2d3e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2d3f0 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
2d400 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
2d410 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
2d420 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
2d430 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
2d440 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
2d450 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
2d460 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
2d470 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
2d480 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
2d490 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
2d4a0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2d4b0 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
2d4c0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
2d4d0 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
2d4e0 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
2d4f0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
2d500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2d510 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
2d520 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
2d530 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
2d540 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
2d550 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
2d560 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
2d570 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2d580 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a  e3_value.  The.*
2d590 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
2d5a0 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63  _dup()] interfac
2d5b0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2d5c0 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77   construct a new
2d5d0 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73   .** protected s
2d5e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f  qlite3_value fro
2d5f0 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  m an unprotected
2d600 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2d610 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
2d620 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
2d630 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
2d640 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
2d650 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
2d660 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
2d670 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
2d680 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
2d690 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2d6a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
2d6b0 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
2d6c0 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
2d6d0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2d6e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
2d6f0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2d700 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
2d710 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
2d720 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
2d730 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
2d740 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
2d750 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
2d760 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
2d770 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
2d780 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
2d790 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
2d7a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
2d7b0 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
2d7c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2d7d0 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
2d7e0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
2d7f0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
2d800 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
2d810 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
2d820 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2d830 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
2d840 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
2d850 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
2d860 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
2d870 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
2d880 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
2d890 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
2d8a0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
2d8b0 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
2d8c0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2d8d0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2d8e0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2d8f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2d900 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
2d910 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
2d920 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
2d930 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2d940 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
2d950 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
2d960 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
2d970 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2d980 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
2d990 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2d9a0 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
2d9b0 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
2d9c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2d9d0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2d9e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2d9f0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
2da00 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
2da10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2da20 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
2da30 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2da40 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
2da50 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2da60 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2da70 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
2da80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2da90 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
2daa0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
2dab0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
2dac0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2dad0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2dae0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
2daf0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2db00 63 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ct sqlite3_value
2db10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
2db20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2db30 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
2db40 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
2db50 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
2db60 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
2db70 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
2db80 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
2db90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
2dba0 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
2dbb0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
2dbc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
2dbd0 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
2dbe0 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
2dbf0 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
2dc00 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2dc10 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
2dc20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2dc30 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2dc40 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2dc50 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
2dc60 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
2dc70 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
2dc80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
2dc90 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
2dca0 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
2dcb0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2dcc0 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
2dcd0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
2dce0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
2dcf0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2dd00 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
2dd10 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
2dd20 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
2dd30 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
2dd40 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2dd50 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
2dd60 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
2dd70 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
2dd80 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
2dd90 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
2dda0 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
2ddb0 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
2ddc0 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
2ddd0 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
2dde0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
2ddf0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
2de00 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
2de10 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
2de20 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
2de30 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  g}.** METHOD: sq
2de40 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2de50 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
2de60 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
2de70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
2de80 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2de90 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
2dea0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
2deb0 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
2dec0 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
2ded0 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
2dee0 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
2def0 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
2df00 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
2df10 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
2df20 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
2df30 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
2df40 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
2df50 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
2df60 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
2df70 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
2df80 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
2df90 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
2dfa0 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
2dfb0 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
2dfc0 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
2dfd0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
2dfe0 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
2dff0 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
2e000 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
2e010 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
2e020 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
2e030 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2e040 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2e050 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
2e060 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2e070 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2e080 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2e090 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
2e0a0 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
2e0b0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
2e0c0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
2e0d0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
2e0e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e0f0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
2e100 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
2e110 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2e120 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
2e130 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
2e140 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
2e150 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
2e160 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
2e170 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
2e180 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
2e190 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
2e1a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
2e1b0 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
2e1c0 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
2e1d0 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
2e1e0 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
2e1f0 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
2e200 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
2e210 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
2e220 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
2e230 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
2e240 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
2e250 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
2e260 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2e270 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
2e280 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
2e290 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
2e2a0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
2e2b0 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
2e2c0 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
2e2d0 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
2e2e0 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
2e2f0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
2e300 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
2e310 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
2e320 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
2e330 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
2e340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
2e350 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2e360 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
2e370 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
2e380 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
2e390 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
2e3a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2e3b0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2e3c0 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f  nd_text16().** o
2e3d0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  r sqlite3_bind_b
2e3e0 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  lob() is a NULL 
2e3f0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
2e400 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2e410 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20  r.** is ignored 
2e420 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75  and the end resu
2e430 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  lt is the same a
2e440 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  s sqlite3_bind_n
2e450 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ull()..**.** ^(I
2e460 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
2e470 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
2e480 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
2e490 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
2e4a0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
2e4b0 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
2e4c0 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
2e4d0 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
2e4e0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2e4f0 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
2e500 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
2e510 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
2e520 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
2e530 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2e540 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2e550 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2e560 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2e570 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
2e580 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
2e590 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
2e5a0 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
2e5b0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
2e5c0 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
2e5d0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
2e5e0 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
2e5f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2e600 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2e610 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
2e620 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
2e630 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2e640 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
2e650 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
2e660 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
2e670 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
2e680 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
2e690 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2e6a0 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65  xt16() or sqlite
2e6b0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
2e6c0 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72  then.** that par
2e6d0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
2e6e0 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
2e6f0 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
2e700 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
2e710 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
2e720 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
2e730 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
2e740 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
2e750 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
2e760 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
2e770 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
2e780 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
2e790 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2e7a0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
2e7b0 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
2e7c0 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
2e7d0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
2e7e0 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
2e7f0 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
2e800 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
2e810 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
2e820 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
2e830 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
2e840 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2e850 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67   BLOB and string
2e860 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61   binding interfa
2e870 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74  ces.** is a dest
2e880 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
2e890 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2e8a0 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
2e8b0 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
2e8c0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
2e8d0 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
2e8e0 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
2e8f0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2e900 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
2e910 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
2e920 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66  ll to bind API f
2e930 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ails..** ^If the
2e940 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2e950 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
2e960 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
2e970 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
2e980 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
2e990 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
2e9a0 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
2e9b0 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
2e9c0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
2e9d0 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
2e9e0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2e9f0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
2ea00 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
2ea10 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
2ea20 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
2ea30 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
2ea40 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
2ea50 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
2ea60 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
2ea70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2ea80 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
2ea90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
2eaa0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2eab0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2eac0 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  4() must be one 
2ead0 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  of.** [SQLITE_UT
2eae0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
2eaf0 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
2eb00 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
2eb10 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f  E_UTF16LE].** to
2eb20 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63   specify the enc
2eb30 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78  oding of the tex
2eb40 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  t in the third p
2eb50 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a  arameter.  If.**
2eb60 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d   the sixth argum
2eb70 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2eb80 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20  ind_text64() is 
2eb90 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
2eba0 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73  * allowed values
2ebb0 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72   shown above, or
2ebc0 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63   if the text enc
2ebd0 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
2ebe0 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65  nt.** from the e
2ebf0 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
2ec00 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70  d by the sixth p
2ec10 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
2ec20 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69  he behavior.** i
2ec30 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2ec40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ec50 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
2ec60 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
2ec70 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
2ec80 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
2ec90 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
2eca0 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
2ecb0 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
2ecc0 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
2ecd0 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
2ece0 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
2ecf0 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
2ed00 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
2ed10 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
2ed20 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
2ed30 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
2ed40 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
2ed50 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
2ed60 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
2ed70 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
2ed80 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
2ed90 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
2eda0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
2edb0 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
2edc0 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
2edd0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
2ede0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
2edf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ee00 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
2ee10 53 2c 49 2c 50 2c 54 29 20 72 6f 75 74 69 6e 65  S,I,P,T) routine
2ee20 20 63 61 75 73 65 73 20 74 68 65 20 49 2d 74 68   causes the I-th
2ee30 20 70 61 72 61 6d 65 74 65 72 20 69 6e 0a 2a 2a   parameter in.**
2ee40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ee50 6d 65 6e 74 5d 20 53 20 74 6f 20 68 61 76 65 20  ment] S to have 
2ee60 61 6e 20 53 51 4c 20 76 61 6c 75 65 20 6f 66 20  an SQL value of 
2ee70 4e 55 4c 4c 2c 20 62 75 74 20 74 6f 20 61 6c 73  NULL, but to als
2ee80 6f 20 62 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74  o be.** associat
2ee90 65 64 20 77 69 74 68 20 74 68 65 20 70 6f 69 6e  ed with the poin
2eea0 74 65 72 20 50 20 6f 66 20 74 79 70 65 20 54 2e  ter P of type T.
2eeb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2eec0 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20  _bind_pointer() 
2eed0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75  routine can be u
2eee0 73 65 64 20 74 6f 20 70 61 73 73 0a 2a 2a 20 68  sed to pass.** h
2eef0 6f 73 74 2d 6c 61 6e 67 75 61 67 65 20 70 6f 69  ost-language poi
2ef00 6e 74 65 72 73 20 69 6e 74 6f 20 5b 61 70 70 6c  nters into [appl
2ef10 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2ef20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
2ef30 2a 2a 20 5e 41 20 70 61 72 61 6d 65 74 65 72 20  ** ^A parameter 
2ef40 74 68 61 74 20 69 73 20 69 6e 69 74 69 61 6c 69  that is initiali
2ef50 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
2ef60 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28  e3_bind_pointer(
2ef70 29 5d 20 61 70 70 65 61 72 73 0a 2a 2a 20 74 6f  )] appears.** to
2ef80 20 62 65 20 61 6e 20 6f 72 64 69 6e 61 72 79 20   be an ordinary 
2ef90 53 51 4c 20 4e 55 4c 4c 20 76 61 6c 75 65 20 74  SQL NULL value t
2efa0 6f 20 65 76 65 72 79 74 68 69 6e 67 20 6f 74 68  o everything oth
2efb0 65 72 20 74 68 61 6e 0a 2a 2a 20 5b 73 71 6c 69  er than.** [sqli
2efc0 74 65 33 5f 76 61 6c 75 65 5f 70 6f 69 6e 74 65  te3_value_pointe
2efd0 72 28 29 5d 2e 20 20 54 68 65 20 54 20 70 61 72  r()].  The T par
2efe0 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
2eff0 20 61 20 73 74 61 74 69 63 20 73 74 72 69 6e 67   a static string
2f000 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
2f010 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
2f020 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2f030 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
2f040 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2f050 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
2f060 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f070 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
2f080 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
2f090 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
2f0a0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
2f0b0 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
2f0c0 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
2f0d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2f0e0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
2f0f0 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
2f100 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2f110 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
2f120 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
2f130 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
2f140 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f150 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
2f160 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
2f170 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
2f180 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2f190 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
2f1a0 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
2f1b0 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
2f1c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
2f1d0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
2f1e0 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
2f1f0 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
2f200 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
2f210 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f220 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
2f230 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2f240 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
2f250 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
2f260 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
2f270 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
2f280 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47   ^[SQLITE_TOOBIG
2f290 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2f2a0 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20  ned if the size 
2f2b0 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  of a string or B
2f2c0 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c  LOB.** exceeds l
2f2d0 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79  imits imposed by
2f2e0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
2f2f0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  ([SQLITE_LIMIT_L
2f300 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53  ENGTH]) or.** [S
2f310 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48  QLITE_MAX_LENGTH
2f320 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  ]..** ^[SQLITE_R
2f330 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
2f340 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
2f350 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
2f360 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
2f370 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
2f380 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
2f390 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
2f3a0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2f3b0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2f3c0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
2f3d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2f3e0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2f3f0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2f400 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2f410 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
2f420 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2f430 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2f440 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2f450 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
2f460 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2f470 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2f480 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2f490 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2f4a0 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
2f4b0 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2f4c0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2f4d0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2f4e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
2f4f0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2f500 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
2f510 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2f520 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
2f530 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
2f540 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2f550 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
2f560 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2f570 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
2f580 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2f590 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
2f5a0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
2f5b0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
2f5c0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63  ite3_stmt*,int,c
2f5d0 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76  onst char*,int,v
2f5e0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2f5f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2f600 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2f610 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2f620 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2f630 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2f640 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2f650 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73  text64(sqlite3_s
2f660 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2f670 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
2f680 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
2f690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f6a0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
2f6b0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
2f6c0 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71  ncoding);.int sq
2f6d0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2f6e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2f6f0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
2f700 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2f710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69  sqlite3_bind_poi
2f720 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 73 74 6d  nter(sqlite3_stm
2f730 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 2a 2c 20  t*, int, void*, 
2f740 63 6f 6e 73 74 20 63 68 61 72 2a 29 3b 0a 69 6e  const char*);.in
2f750 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
2f760 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2f770 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
2f780 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  n);.int sqlite3_
2f790 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28  bind_zeroblob64(
2f7a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f7b0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  nt, sqlite3_uint
2f7c0 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
2f7d0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2f7e0 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
2f7f0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2f800 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2f810 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
2f820 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
2f830 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
2f840 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
2f850 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
2f860 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
2f870 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2f880 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
2f890 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
2f8a0 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
2f8b0 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
2f8c0 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
2f8d0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
2f8e0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
2f8f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2f900 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
2f910 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
2f920 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
2f930 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2f940 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
2f950 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
2f960 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
2f970 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
2f980 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
2f990 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
2f9a0 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
2f9b0 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
2f9c0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
2f9d0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
2f9e0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
2f9f0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
2fa00 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
2fa10 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
2fa20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
2fa30 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2fa40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2fa50 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2fa60 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2fa70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2fa80 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
2fa90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2faa0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2fab0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2fac0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2fad0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2fae0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2faf0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
2fb00 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
2fb10 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2fb20 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2fb30 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2fb40 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
2fb50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2fb60 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
2fb70 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
2fb80 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2fb90 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2fba0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
2fbb0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
2fbc0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
2fbd0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2fbe0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2fbf0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
2fc00 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
2fc10 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
2fc20 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2fc30 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
2fc40 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
2fc50 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
2fc60 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
2fc70 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
2fc80 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
2fc90 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
2fca0 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
2fcb0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2fcc0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
2fcd0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
2fce0 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
2fcf0 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
2fd00 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
2fd10 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
2fd20 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
2fd30 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2fd40 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
2fd50 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2fd60 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
2fd70 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
2fd80 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
2fd90 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
2fda0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
2fdb0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
2fdc0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
2fdd0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2fde0 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
2fdf0 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
2fe00 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2fe10 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
2fe20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
2fe30 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
2fe40 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
2fe50 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 0a  3_prepare16()],.
2fe60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2fe70 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20  are16_v2()], or 
2fe80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2fe90 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v3()]..**.** 
2fea0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2feb0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2fec0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2fed0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2fee0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2fef0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2ff00 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ff10 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
2ff20 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2ff30 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2ff40 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
2ff50 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
2ff60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
2ff70 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
2ff80 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
2ff90 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ame.** METHOD: s
2ffa0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2ffb0 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
2ffc0 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
2ffd0 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
2ffe0 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
2fff0 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
30000 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
30010 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
30020 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
30030 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
30040 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
30050 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
30060 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
30070 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
30080 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
30090 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
300a0 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
300b0 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
300c0 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
300d0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
300e0 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
300f0 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
30100 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
30110 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
30120 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
30130 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
30140 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
30150 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
30160 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
30170 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
30180 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30190 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
301a0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
301b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
301c0 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  e()]..*/.int sql
301d0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
301e0 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65  ter_index(sqlite
301f0 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63  3_stmt*, const c
30200 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a  har *zName);../*
30210 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
30220 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73  set All Bindings
30230 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53   On A Prepared S
30240 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48  tatement.** METH
30250 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
30260 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
30270 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
30280 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
30290 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
302a0 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
302b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
302c0 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
302d0 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
302e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
302f0 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
30300 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
30310 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
30320 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
30330 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
30340 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
30350 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
30360 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
30370 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
30380 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
30390 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
303a0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
303b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
303c0 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
303d0 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
303e0 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
303f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
30400 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
30410 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 61 74   returns 0, that
30420 20 6d 65 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b   means the .** [
30430 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30440 6e 74 5d 20 72 65 74 75 72 6e 73 20 6e 6f 20 64  nt] returns no d
30450 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
30460 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
30470 2a 20 5e 48 6f 77 65 76 65 72 2c 20 6a 75 73 74  * ^However, just
30480 20 62 65 63 61 75 73 65 20 74 68 69 73 20 72 6f   because this ro
30490 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
304a0 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 20  positive number 
304b0 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e  does not.** mean
304c0 20 74 68 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72   that one or mor
304d0 65 20 72 6f 77 73 20 6f 66 20 64 61 74 61 20 77  e rows of data w
304e0 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64 2e  ill be returned.
304f0 20 20 5e 41 20 53 45 4c 45 43 54 20 73 74 61 74    ^A SELECT stat
30500 65 6d 65 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ement.** will al
30510 77 61 79 73 20 68 61 76 65 20 61 20 70 6f 73 69  ways have a posi
30520 74 69 76 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  tive sqlite3_col
30530 75 6d 6e 5f 63 6f 75 6e 74 28 29 20 62 75 74 20  umn_count() but 
30540 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
30550 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65  .** WHERE clause
30560 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64   constraints and
30570 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6e 74 65   the table conte
30580 6e 74 2c 20 69 74 20 6d 69 67 68 74 20 72 65 74  nt, it might ret
30590 75 72 6e 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a  urn no rows..**.
305a0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
305b0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
305c0 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
305d0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
305e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
305f0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
30600 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
30610 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
30620 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
30630 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
30640 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
30650 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
30660 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
30670 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
30680 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
30690 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
306a0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
306b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
306c0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
306d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
306e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
306f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
30700 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
30710 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
30720 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
30730 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
30740 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
30750 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
30760 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
30770 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
30780 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
30790 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
307a0 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
307b0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
307c0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
307d0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
307e0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
307f0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
30800 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
30810 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
30820 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
30830 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
30840 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
30850 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30860 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
30870 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
30880 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
30890 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
308a0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
308b0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
308c0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
308d0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
308e0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
308f0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
30900 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
30910 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
30920 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
30930 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
30940 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
30950 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
30960 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
30970 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
30980 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
30990 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
309a0 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
309b0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
309c0 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
309d0 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
309e0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
309f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
30a00 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
30a10 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
30a20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
30a30 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
30a40 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
30a50 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
30a60 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
30a70 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
30a80 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
30a90 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
30aa0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
30ab0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
30ac0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
30ad0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
30ae0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
30af0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
30b00 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
30b10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
30b20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30b30 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
30b40 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
30b50 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
30b60 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
30b70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30b80 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
30b90 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
30ba0 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  lt.** METHOD: sq
30bb0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
30bc0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
30bd0 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
30be0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
30bf0 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
30c00 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
30c10 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
30c20 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
30c30 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
30c40 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
30c50 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
30c60 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
30c70 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
30c80 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
30c90 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
30ca0 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
30cb0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
30cc0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
30cd0 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
30ce0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
30cf0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
30d00 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
30d10 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
30d20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
30d30 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
30d40 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
30d50 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
30d60 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
30d70 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
30d80 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
30d90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30da0 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
30db0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
30dc0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
30dd0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
30de0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
30df0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
30e00 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
30e10 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
30e20 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
30e30 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
30e40 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
30e50 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
30e60 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
30e70 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
30e80 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
30e90 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
30ea0 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
30eb0 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
30ec0 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
30ed0 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
30ee0 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
30ef0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
30f00 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
30f10 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
30f20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
30f30 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
30f40 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
30f50 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
30f60 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
30f70 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
30f80 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
30f90 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
30fa0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
30fb0 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
30fc0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
30fd0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
30fe0 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
30ff0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
31000 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
31010 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
31020 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
31030 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
31040 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
31050 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
31060 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
31070 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
31080 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
31090 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
310a0 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
310b0 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
310c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
310d0 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
310e0 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
310f0 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
31100 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
31110 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
31120 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
31130 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
31140 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
31150 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
31160 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
31170 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
31180 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
31190 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
311a0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
311b0 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
311c0 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
311d0 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
311e0 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
311f0 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
31200 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
31210 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
31220 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
31230 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
31240 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
31250 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
31260 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
31270 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
31280 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
31290 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
312a0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
312b0 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
312c0 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
312d0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
312e0 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
312f0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
31300 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
31310 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
31320 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
31330 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
31340 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
31350 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
31360 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
31370 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
31380 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
31390 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
313a0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
313b0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
313c0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
313d0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
313e0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
313f0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
31400 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
31410 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
31420 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
31430 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
31440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
31450 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
31460 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
31470 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
31480 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
31490 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
314a0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
314b0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
314c0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
314d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
314e0 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
314f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
31500 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
31510 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
31520 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
31530 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
31540 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
31550 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
31560 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
31570 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
31580 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
31590 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
315a0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
315b0 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
315c0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
315d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
315e0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
315f0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
31600 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
31610 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
31620 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
31630 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
31640 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
31650 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
31660 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
31670 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
31680 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
31690 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
316a0 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
316b0 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
316c0 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
316d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
316e0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
316f0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
31700 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
31710 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
31720 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
31730 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
31740 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
31750 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
31760 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
31770 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
31780 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
31790 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
317a0 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
317b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
317c0 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
317d0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
317e0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
317f0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
31800 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
31810 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
31820 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
31830 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
31840 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
31850 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
31860 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
31870 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
31880 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
31890 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
318a0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
318b0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
318c0 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
318d0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
318e0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
318f0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
31900 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
31910 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
31920 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
31930 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
31940 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
31950 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
31960 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
31970 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
31980 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
31990 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
319a0 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
319b0 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
319c0 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
319d0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
319e0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
319f0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
31a00 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
31a10 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
31a20 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
31a30 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
31a40 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31a50 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
31a60 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
31a70 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
31a80 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
31a90 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
31aa0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
31ab0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
31ac0 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
31ad0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
31ae0 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
31af0 73 69 6e 67 20 61 6e 79 20 6f 66 0a 2a 2a 20 5b  sing any of.** [
31b00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
31b10 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
31b20 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b  prepare_v3()], [
31b30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
31b40 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  6_v2()],.** or [
31b50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
31b60 36 5f 76 33 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v3()] or one o
31b70 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
31b80 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
31b90 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
31ba0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
31bb0 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
31bc0 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
31bd0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
31be0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
31bf0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
31c00 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
31c10 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
31c20 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
31c30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
31c40 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
31c50 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
31c60 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
31c70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
31c80 65 20 6e 65 77 65 72 20 22 76 58 22 20 69 6e 74  e newer "vX" int
31c90 65 72 66 61 63 65 73 0a 2a 2a 20 5b 73 71 6c 69  erfaces.** [sqli
31ca0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29  te3_prepare_v3()
31cb0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ], [sqlite3_prep
31cc0 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
31cd0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33  te3_prepare16_v3
31ce0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
31cf0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
31d00 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
31d10 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
31d20 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
31d30 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
31d40 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
31d50 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
31d60 65 0a 2a 2a 20 6e 65 77 20 22 76 58 22 20 69 6e  e.** new "vX" in
31d70 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
31d80 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
31d90 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
31da0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
31db0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
31dc0 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
31dd0 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
31de0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
31df0 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
31e00 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
31e10 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
31e20 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
31e30 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
31e40 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
31e50 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
31e60 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
31e70 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
31e80 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
31e90 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
31ea0 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
31eb0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
31ec0 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
31ed0 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
31ee0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
31ef0 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
31f00 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
31f10 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
31f20 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
31f30 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
31f40 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
31f50 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
31f60 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
31f70 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
31f80 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
31f90 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
31fa0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
31fb0 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
31fc0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
31fd0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
31fe0 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
31ff0 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
32000 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
32010 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
32020 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
32030 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
32040 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
32050 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
32060 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
32070 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
32080 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
32090 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
320a0 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
320b0 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
320c0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
320d0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
320e0 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
320f0 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
32100 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
32110 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
32120 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
32130 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
32140 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
32150 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
32160 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
32170 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
32180 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
32190 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
321a0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
321b0 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
321c0 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
321d0 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
321e0 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
321f0 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
32200 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
32210 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
32220 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
32230 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
32240 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
32250 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
32260 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
32270 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
32280 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
32290 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
322a0 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
322b0 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
322c0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
322d0 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
322e0 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
322f0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
32300 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
32310 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
32320 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
32330 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
32340 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
32350 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
32360 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
32370 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
32380 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
32390 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
323a0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
323b0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
323c0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
323d0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
323e0 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
323f0 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
32400 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
32410 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
32420 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
32430 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
32440 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
32450 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
32460 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
32470 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
32480 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
32490 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
324a0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
324b0 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
324c0 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
324d0 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
324e0 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
324f0 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
32500 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
32510 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32520 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
32530 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
32540 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
32550 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
32560 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
32570 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
32580 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
32590 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
325a0 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
325b0 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
325c0 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
325d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
325e0 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
325f0 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
32600 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
32610 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
32620 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
32630 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
32640 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
32650 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
32660 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
32670 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
32680 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
32690 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
326a0 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
326b0 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
326c0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
326d0 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
326e0 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
326f0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
32700 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
32710 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
32720 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
32730 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
32740 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
32750 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
32760 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
32770 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
32780 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
32790 2e 20 20 42 75 74 20 61 66 74 65 72 20 5b 76 65  .  But after [ve
327a0 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20  rsion 3.6.23.1] 
327b0 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e  ([dateof:3.6.23.
327c0 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  1],.** sqlite3_s
327d0 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
327e0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
327f0 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
32800 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
32810 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
32820 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
32830 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
32840 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
32850 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
32860 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
32870 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
32880 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
32890 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
328a0 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
328b0 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
328c0 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
328d0 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
328e0 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
328f0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
32900 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
32910 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
32920 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
32930 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
32940 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
32950 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
32960 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
32970 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
32980 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
32990 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
329a0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
329b0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
329c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
329d0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
329e0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
329f0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
32a00 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
32a10 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
32a20 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
32a30 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
32a40 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
32a50 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
32a60 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
32a70 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
32a80 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
32a90 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
32aa0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
32ab0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
32ac0 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
32ad0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
32ae0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
32af0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
32b00 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
32b10 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
32b20 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  ents.** using [s
32b30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
32b40 33 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  3()] or [sqlite3
32b50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 0a 2a  _prepare_v2()].*
32b60 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  * or [sqlite3_pr
32b70 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
32b80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32b90 65 31 36 5f 76 33 28 29 5d 20 69 6e 73 74 65 61  e16_v3()] instea
32ba0 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
32bb0 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
32bc0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
32bd0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
32be0 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
32bf0 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
32c00 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
32c10 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
32c20 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
32c30 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
32c40 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
32c50 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73   "vX" interfaces
32c60 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
32c70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
32c80 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
32c90 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
32ca0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
32cb0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
32cc0 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult set.** METHO
32cd0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
32ce0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32cf0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
32d00 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
32d10 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
32d20 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
32d30 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
32d40 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
32d50 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
32d60 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
32d70 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
32d80 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
32d90 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
32da0 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
32db0 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
32dc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
32dd0 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
32de0 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
32df0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
32e00 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
32e10 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
32e20 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
32e30 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
32e40 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
32e50 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
32e60 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
32e70 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
32e80 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
32e90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
32ea0 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
32eb0 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
32ec0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
32ed0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
32ee0 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
32ef0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
32f00 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
32f10 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
32f20 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
32f30 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
32f40 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
32f50 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
32f60 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
32f70 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
32f80 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
32f90 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
32fa0 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
32fb0 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
32fc0 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
32fd0 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
32fe0 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
32ff0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
33000 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
33010 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
33020 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
33030 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
33040 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
33050 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33060 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
33070 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
33080 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
33090 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
330a0 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
330b0 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
330c0 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
330d0 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
330e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
330f0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
33100 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
33110 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
33120 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
33130 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
33140 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
33150 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
33160 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
33170 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
33180 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
33190 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
331a0 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
331b0 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
331c0 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
331d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
331e0 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
331f0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
33200 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
33210 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
33220 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
33230 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
33240 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
33250 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
33260 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
33270 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
33280 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
33290 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
332a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
332b0 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
332c0 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
332d0 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
332e0 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
332f0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
33300 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
33310 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
33320 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
33330 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
33340 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
33350 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
33360 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
33370 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
33380 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
33390 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
333a0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
333b0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
333c0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72  .**.** <b>Summar
333d0 79 3a 3c 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b  y:</b>.** <block
333e0 71 75 6f 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72  quote><table bor
333f0 64 65 72 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e  der=0 cellpaddin
33400 67 3d 30 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d  g=0 cellspacing=
33410 30 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  0>.** <tr><td><b
33420 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
33430 62 6c 6f 62 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  blob</b><td>&rar
33440 72 3b 3c 74 64 3e 42 4c 4f 42 20 72 65 73 75 6c  r;<td>BLOB resul
33450 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
33460 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
33470 6f 75 62 6c 65 3c 2f 62 3e 3c 74 64 3e 26 72 61  ouble</b><td>&ra
33480 72 72 3b 3c 74 64 3e 52 45 41 4c 20 72 65 73 75  rr;<td>REAL resu
33490 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  lt.** <tr><td><b
334a0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
334b0 69 6e 74 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  int</b><td>&rarr
334c0 3b 3c 74 64 3e 33 32 2d 62 69 74 20 49 4e 54 45  ;<td>32-bit INTE
334d0 47 45 52 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74  GER result.** <t
334e0 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
334f0 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 3c 2f 62  _column_int64</b
33500 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 36  ><td>&rarr;<td>6
33510 34 2d 62 69 74 20 49 4e 54 45 47 45 52 20 72 65  4-bit INTEGER re
33520 73 75 6c 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  sult.** <tr><td>
33530 3c 62 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  <b>sqlite3_colum
33540 6e 5f 74 65 78 74 3c 2f 62 3e 3c 74 64 3e 26 72  n_text</b><td>&r
33550 61 72 72 3b 3c 74 64 3e 55 54 46 2d 38 20 54 45  arr;<td>UTF-8 TE
33560 58 54 20 72 65 73 75 6c 74 0a 2a 2a 20 3c 74 72  XT result.** <tr
33570 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
33580 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 3c 2f 62  column_text16</b
33590 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55  ><td>&rarr;<td>U
335a0 54 46 2d 31 36 20 54 45 58 54 20 72 65 73 75 6c  TF-16 TEXT resul
335b0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  t.** <tr><td><b>
335c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
335d0 61 6c 75 65 3c 2f 62 3e 3c 74 64 3e 26 72 61 72  alue</b><td>&rar
335e0 72 3b 3c 74 64 3e 54 68 65 20 72 65 73 75 6c 74  r;<td>The result
335f0 20 61 73 20 61 6e 20 0a 2a 2a 20 5b 73 71 6c 69   as an .** [sqli
33600 74 65 33 5f 76 61 6c 75 65 7c 75 6e 70 72 6f 74  te3_value|unprot
33610 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
33620 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  lue] object..** 
33630 3c 74 72 3e 3c 74 64 3e 26 6e 62 73 70 3b 3c 74  <tr><td>&nbsp;<t
33640 64 3e 26 6e 62 73 70 3b 3c 74 64 3e 26 6e 62 73  d>&nbsp;<td>&nbs
33650 70 3b 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62  p;.** <tr><td><b
33660 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
33670 62 79 74 65 73 3c 2f 62 3e 3c 74 64 3e 26 72 61  bytes</b><td>&ra
33680 72 72 3b 3c 74 64 3e 53 69 7a 65 20 6f 66 20 61  rr;<td>Size of a
33690 20 42 4c 4f 42 0a 2a 2a 20 6f 72 20 61 20 55 54   BLOB.** or a UT
336a0 46 2d 38 20 54 45 58 54 20 72 65 73 75 6c 74 20  F-8 TEXT result 
336b0 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74 72 3e  in bytes.** <tr>
336c0 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f 63  <td><b>sqlite3_c
336d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 26 6e 62  olumn_bytes16&nb
336e0 73 70 3b 26 6e 62 73 70 3b 3c 2f 62 3e 0a 2a 2a  sp;&nbsp;</b>.**
336f0 20 3c 74 64 3e 26 72 61 72 72 3b 26 6e 62 73 70   <td>&rarr;&nbsp
33700 3b 26 6e 62 73 70 3b 3c 74 64 3e 53 69 7a 65 20  ;&nbsp;<td>Size 
33710 6f 66 20 55 54 46 2d 31 36 0a 2a 2a 20 54 45 58  of UTF-16.** TEX
33720 54 20 69 6e 20 62 79 74 65 73 0a 2a 2a 20 3c 74  T in bytes.** <t
33730 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33  r><td><b>sqlite3
33740 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 3c 2f 62 3e  _column_type</b>
33750 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 44 65  <td>&rarr;<td>De
33760 66 61 75 6c 74 0a 2a 2a 20 64 61 74 61 74 79 70  fault.** datatyp
33770 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 0a  e of the result.
33780 2a 2a 20 3c 2f 74 61 62 6c 65 3e 3c 2f 62 6c 6f  ** </table></blo
33790 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 3c  ckquote>.**.** <
337a0 62 3e 44 65 74 61 69 6c 73 3a 3c 2f 62 3e 0a 2a  b>Details:</b>.*
337b0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
337c0 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
337d0 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
337e0 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
337f0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
33800 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
33810 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
33820 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
33830 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
33840 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
33850 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
33860 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
33870 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
33880 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
33890 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
338a0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
338b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
338c0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
338d0 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
338e0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
338f0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
33900 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
33910 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
33920 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
33930 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
33940 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
33950 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
33960 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
33970 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
33980 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
33990 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
339a0 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
339b0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
339c0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
339d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
339e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
339f0 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
33a00 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
33a10 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
33a20 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
33a30 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
33a40 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
33a50 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
33a60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
33a70 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
33a80 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
33a90 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
33aa0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
33ab0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
33ac0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
33ad0 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
33ae0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
33af0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
33b00 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
33b10 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
33b20 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
33b30 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
33b40 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
33b50 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
33b60 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
33b70 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
33b80 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
33b90 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
33ba0 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
33bb0 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
33bc0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
33bd0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
33be0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
33bf0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
33c00 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33c10 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
33c20 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
33c30 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
33c40 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
33c50 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
33c60 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
33c70 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
33c80 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
33c90 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
33ca0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 73 69 78  ** The first six
33cb0 20 69 6e 74 65 72 66 61 63 65 73 20 28 5f 62 6c   interfaces (_bl
33cc0 6f 62 2c 20 5f 64 6f 75 62 6c 65 2c 20 5f 69 6e  ob, _double, _in
33cd0 74 2c 20 5f 69 6e 74 36 34 2c 20 5f 74 65 78 74  t, _int64, _text
33ce0 2c 20 61 6e 64 20 5f 74 65 78 74 31 36 29 0a 2a  , and _text16).*
33cf0 2a 20 65 61 63 68 20 72 65 74 75 72 6e 20 74 68  * each return th
33d00 65 20 76 61 6c 75 65 20 6f 66 20 61 20 72 65 73  e value of a res
33d10 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 20 61 20  ult column in a 
33d20 73 70 65 63 69 66 69 63 20 64 61 74 61 20 66 6f  specific data fo
33d30 72 6d 61 74 2e 20 20 49 66 0a 2a 2a 20 74 68 65  rmat.  If.** the
33d40 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
33d50 73 20 6e 6f 74 20 69 6e 69 74 69 61 6c 6c 79 20  s not initially 
33d60 69 6e 20 74 68 65 20 72 65 71 75 65 73 74 65 64  in the requested
33d70 20 66 6f 72 6d 61 74 20 28 66 6f 72 20 65 78 61   format (for exa
33d80 6d 70 6c 65 2c 0a 2a 2a 20 69 66 20 74 68 65 20  mple,.** if the 
33d90 71 75 65 72 79 20 72 65 74 75 72 6e 73 20 61 6e  query returns an
33da0 20 69 6e 74 65 67 65 72 20 62 75 74 20 74 68 65   integer but the
33db0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33dc0 74 65 78 74 28 29 20 69 6e 74 65 72 66 61 63 65  text() interface
33dd0 0a 2a 2a 20 69 73 20 75 73 65 64 20 74 6f 20 65  .** is used to e
33de0 78 74 72 61 63 74 20 74 68 65 20 76 61 6c 75 65  xtract the value
33df0 29 20 74 68 65 6e 20 61 6e 20 61 75 74 6f 6d 61  ) then an automa
33e00 74 69 63 20 74 79 70 65 20 63 6f 6e 76 65 72 73  tic type convers
33e10 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
33e20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33e30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
33e40 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
33e50 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
33e60 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
33e70 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
33e80 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
33e90 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
33ea0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
33eb0 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
33ec0 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
33ed0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
33ee0 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
33ef0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
33f00 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
33f10 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
33f20 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 20  ..** The return 
33f30 76 61 6c 75 65 20 6f 66 20 73 71 6c 69 74 65 33  value of sqlite3
33f40 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 63  _column_type() c
33f50 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
33f60 63 69 64 65 20 77 68 69 63 68 0a 2a 2a 20 6f 66  cide which.** of
33f70 20 74 68 65 20 66 69 72 73 74 20 73 69 78 20 69   the first six i
33f80 6e 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20  nterface should 
33f90 62 65 20 75 73 65 64 20 74 6f 20 65 78 74 72 61  be used to extra
33fa0 63 74 20 74 68 65 20 63 6f 6c 75 6d 6e 20 76 61  ct the column va
33fb0 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75  lue..** The valu
33fc0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
33fd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
33fe0 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
33ff0 69 6e 67 66 75 6c 20 69 66 20 6e 6f 0a 2a 2a 20  ingful if no.** 
34000 61 75 74 6f 6d 61 74 69 63 20 74 79 70 65 20 63  automatic type c
34010 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
34020 6f 63 63 75 72 72 65 64 20 66 6f 72 20 74 68 65  occurred for the
34030 20 76 61 6c 75 65 20 69 6e 20 71 75 65 73 74 69   value in questi
34040 6f 6e 2e 20 20 0a 2a 2a 20 41 66 74 65 72 20 61  on.  .** After a
34050 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
34060 2c 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  , the result of 
34070 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
34080 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
34090 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2c 20 74   is undefined, t
340a0 68 6f 75 67 68 20 68 61 72 6d 6c 65 73 73 2e 20  hough harmless. 
340b0 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
340c0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
340d0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
340e0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
340f0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
34100 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
34110 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
34120 2a 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75  *.** If the resu
34130 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
34140 61 20 54 45 58 54 20 73 74 72 69 6e 67 2c 20 74  a TEXT string, t
34150 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
34160 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
34170 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * or sqlite3_col
34180 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 69 6e  umn_bytes16() in
34190 74 65 72 66 61 63 65 73 20 63 61 6e 20 62 65 20  terfaces can be 
341a0 75 73 65 64 20 74 6f 20 64 65 74 65 72 6d 69 6e  used to determin
341b0 65 20 74 68 65 20 73 69 7a 65 0a 2a 2a 20 6f 66  e the size.** of
341c0 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
341d0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ring..**.** ^If 
341e0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
341f0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
34200 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
34210 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
34220 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
34230 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
34240 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
34250 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
34260 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
34270 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
34280 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
34290 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
342a0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
342b0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
342c0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
342d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
342e0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
342f0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
34300 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
34310 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
34320 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
34330 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
34340 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
34350 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
34360 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
34370 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
34380 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
34390 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
343a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
343b0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
343c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
343d0 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
343e0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
343f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
34400 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
34410 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
34420 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
34430 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
34440 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
34450 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
34460 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
34470 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
34480 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
34490 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
344a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
344b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
344c0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
344d0 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
344e0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
344f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
34500 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
34510 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
34520 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
34530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34540 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
34550 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
34560 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
34570 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
34580 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
34590 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
345a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
345b0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
345c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
345d0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
345e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
345f0 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
34600 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
34610 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
34620 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
34630 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
34640 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
34650 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
34660 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
34670 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
34680 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
34690 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
346a0 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
346b0 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
346c0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
346d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
346e0 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
346f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
34700 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
34710 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
34720 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
34730 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
34740 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
34750 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
34760 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
34770 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
34780 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34790 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
347a0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
347b0 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
347c0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
347d0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
347e0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
347f0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
34800 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
34810 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
34820 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  ointer..**.** <b
34830 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54  >Warning:</b> ^T
34840 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
34850 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
34860 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
34870 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
34880 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
34890 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20  ue] object.  In 
348a0 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  a multithreaded 
348b0 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20  environment,.** 
348c0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
348d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
348e0 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  ect may only be 
348f0 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68  used safely with
34900 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
34910 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
34920 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
34930 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
34940 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
34950 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
34960 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
34970 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
34980 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
34990 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
349a0 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
349b0 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
349c0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
349d0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
349e0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
349f0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
34a00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34a10 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65  bytes()], the be
34a20 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68  havior is not th
34a30 72 65 61 64 73 61 66 65 2e 0a 2a 2a 20 48 65 6e  readsafe..** Hen
34a40 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
34a50 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 20 69  column_value() i
34a60 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73 20 6e  nterface.** is n
34a70 6f 72 6d 61 6c 6c 79 20 6f 6e 6c 79 20 75 73 65  ormally only use
34a80 66 75 6c 20 77 69 74 68 69 6e 20 74 68 65 20 69  ful within the i
34a90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
34aa0 20 0a 2a 2a 20 5b 61 70 70 6c 69 63 61 74 69 6f   .** [applicatio
34ab0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
34ac0 6e 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 76 69 72  nctions] or [vir
34ad0 74 75 61 6c 20 74 61 62 6c 65 73 5d 2c 20 6e 6f  tual tables], no
34ae0 74 20 77 69 74 68 69 6e 0a 2a 2a 20 74 6f 70 2d  t within.** top-
34af0 6c 65 76 65 6c 20 61 70 70 6c 69 63 61 74 69 6f  level applicatio
34b00 6e 20 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  n code..**.** Th
34b10 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
34b20 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
34b30 63 6f 6e 76 65 72 74 20 74 68 65 20 64 61 74 61  convert the data
34b40 74 79 70 65 20 6f 66 20 74 68 65 20 72 65 73 75  type of the resu
34b50 6c 74 2e 0a 2a 2a 20 5e 46 6f 72 20 65 78 61 6d  lt..** ^For exam
34b60 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
34b70 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
34b80 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
34b90 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
34ba0 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
34bb0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
34bc0 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
34bd0 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
34be0 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
34bf0 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
34c00 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
34c10 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
34c20 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
34c30 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
34c40 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
34c50 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
34c60 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
34c70 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
34c80 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
34c90 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
34ca0 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
34cb0 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
34cc0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
34cd0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
34ce0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
34cf0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
34d00 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
34d10 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
34d20 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
34d30 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
34d40 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
34d50 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
34d60 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
34d70 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
34d80 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
34d90 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
34da0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
34db0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
34dc0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
34dd0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
34de0 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
34df0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
34e00 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
34e10 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
34e20 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
34e30 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
34e40 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
34e50 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
34e60 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
34e70 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
34e80 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
34e90 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
34ea0 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
34eb0 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  R.** <tr><td>  F
34ec0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
34ed0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
34ee0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
34ef0 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
34f00 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
34f10 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
34f20 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a   [CAST] to BLOB.
34f30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
34f40 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
34f50 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
34f60 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
34f70 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
34f80 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
34f90 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
34fa0 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
34fb0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
34fc0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
34fd0 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
34fe0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
34ff0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
35000 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
35010 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
35020 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
35030 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
35040 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
35050 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
35060 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
35070 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
35080 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
35090 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
350a0 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
350b0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
350c0 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65   when type conve
350d0 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f  rsions occur, po
350e0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
350f0 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c  by prior.** call
35100 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
35110 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  umn_blob(), sqli
35120 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
35130 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c  ), and/or.** sql
35140 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35150 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61  16() may be inva
35160 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65  lidated..** Type
35170 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64   conversions and
35180 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64   pointer invalid
35190 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63  ations might occ
351a0 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c  ur.** in the fol
351b0 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a  lowing cases:.**
351c0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
351d0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
351e0 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61  tent is a BLOB a
351f0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
35200 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20  n_text() or.**  
35210 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
35220 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
35230 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74  alled.  A zero-t
35240 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a  erminator might.
35250 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20  **      need to 
35260 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  be added to the 
35270 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20  string.</li>.** 
35280 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
35290 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
352a0 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  8 text and sqlit
352b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
352c0 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  6() or.**      s
352d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
352e0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
352f0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
35300 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
35310 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
35320 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  16.</li>.** <li>
35330 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
35340 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74  tent is UTF-16 t
35350 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
35360 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
35370 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
35380 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
35390 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
353a0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
353b0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
353c0 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e    to UTF-8.</li>
353d0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
353e0 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74  ^Conversions bet
353f0 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e  ween UTF-16be an
35400 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61  d UTF-16le are a
35410 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c  lways done in pl
35420 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f  ace and do.** no
35430 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70  t invalidate a p
35440 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68  rior pointer, th
35450 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74  ough of course t
35460 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
35470 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  e buffer.** that
35480 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74   the prior point
35490 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69  er references wi
354a0 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64  ll have been mod
354b0 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69  ified.  Other ki
354c0 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72  nds.** of conver
354d0 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e  sion are done in
354e0 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69   place when it i
354f0 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20  s possible, but 
35500 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a  sometimes they.*
35510 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62  * are not possib
35520 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20  le and in those 
35530 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e  cases prior poin
35540 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64  ters are invalid
35550 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ated..**.** The 
35560 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73  safest policy is
35570 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
35580 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
35590 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
355a0 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
355b0 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
355c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
355d0 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
355e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
355f0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
35600 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
35610 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
35620 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
35630 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
35640 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
35650 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
35660 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
35670 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35680 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
35690 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
356a0 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
356b0 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
356c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
356d0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
356e0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
356f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35700 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
35710 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
35720 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
35730 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
35740 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
35750 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
35760 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
35770 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
35780 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
35790 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
357a0 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
357b0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
357c0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
357d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
357e0 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
357f0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
35800 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
35810 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
35820 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
35830 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
35840 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
35850 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
35860 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
35870 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
35880 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
35890 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
358a0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
358b0 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
358c0 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
358d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
358e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
358f0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
35900 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
35910 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
35920 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
35930 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
35940 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
35950 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
35960 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 6e 6f 74  tically.  Do not
35970 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
35980 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  rs returned.** f
35990 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
359a0 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
359b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
359c0 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
359d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
359e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
359f0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
35a00 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
35a10 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
35a20 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
35a30 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
35a40 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
35a50 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
35a60 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
35a70 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
35a80 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
35a90 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
35aa0 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
35ab0 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
35ac0 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
35ad0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
35ae0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
35af0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
35b00 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
35b10 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
35b20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
35b30 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
35b40 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
35b50 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
35b60 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
35b70 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
35b80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35b90 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
35ba0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
35bb0 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
35bc0 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
35bd0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
35be0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
35bf0 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
35c00 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
35c10 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
35c20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
35c30 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
35c40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35c50 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
35c60 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
35c70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
35c80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
35c90 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
35ca0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
35cb0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
35cc0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
35cd0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
35ce0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
35cf0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
35d00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
35d10 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
35d20 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
35d30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
35d40 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
35d50 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
35d60 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
35d70 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
35d80 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  DESTRUCTOR: sqli
35d90 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
35da0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
35db0 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
35dc0 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
35dd0 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
35de0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
35df0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
35e00 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
35e10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
35e20 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
35e30 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
35e40 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
35e50 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
35e60 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
35e70 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
35e80 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
35e90 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
35ea0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
35eb0 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
35ec0 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
35ed0 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
35ee0 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
35ef0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
35f00 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
35f10 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
35f20 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
35f30 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
35f40 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
35f50 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
35f60 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
35f70 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
35f80 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
35f90 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
35fa0 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
35fb0 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
35fc0 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
35fd0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
35fe0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
35ff0 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
36000 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
36010 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
36020 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
36030 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
36040 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
36050 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
36060 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
36070 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
36080 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
36090 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
360a0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
360b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
360c0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
360d0 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
360e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
360f0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
36100 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
36110 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
36120 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
36130 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
36140 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
36150 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
36160 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
36170 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
36180 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
36190 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
361a0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
361b0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
361c0 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
361d0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
361e0 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
361f0 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
36200 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
36210 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
36220 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  */.int sqlite3_f
36230 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
36240 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
36250 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
36260 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
36270 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
36280 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
36290 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54  te3_stmt.**.** T
362a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
362b0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
362c0 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
362d0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
362e0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
362f0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
36300 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
36310 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
36320 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
36330 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
36340 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
36350 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
36360 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
36370 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
36380 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
36390 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
363a0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
363b0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
363c0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
363d0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
363e0 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
363f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
36400 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
36410 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
36420 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
36430 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
36440 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
36450 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
36460 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
36470 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
36480 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
36490 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
364a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
364b0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
364c0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
364d0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
364e0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
364f0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
36500 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
36510 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
36520 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
36530 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
36540 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
36550 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
36560 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
36570 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
36580 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
36590 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
365a0 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
365b0 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
365c0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
365d0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
365e0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
365f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
36600 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
36610 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
36620 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
36630 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
36640 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
36650 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
36660 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
36670 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
36680 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
36690 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
366a0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
366b0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
366c0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
366d0 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
366e0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
366f0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
36700 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
36710 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36720 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
36730 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
36740 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36750 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
36760 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
36770 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
36780 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
36790 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
367a0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
367b0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
367c0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
367d0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
367e0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
367f0 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
36800 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
36810 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
36820 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
36830 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
36840 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
36850 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
36860 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
36870 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
36880 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
36890 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
368a0 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
368b0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
368c0 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
368d0 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
368e0 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
368f0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
36900 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
36910 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
36920 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
36930 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
36940 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
36950 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36960 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
36970 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
36980 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
36990 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
369a0 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
369b0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
369c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
369d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
369e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
369f0 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
36a00 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
36a10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
36a20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
36a30 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
36a40 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
36a50 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
36a60 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
36a70 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
36a80 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
36a90 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
36aa0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
36ab0 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
36ac0 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
36ad0 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
36ae0 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
36af0 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
36b00 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
36b10 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
36b20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
36b30 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
36b40 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
36b50 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
36b60 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
36b70 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
36b80 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
36b90 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
36ba0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
36bb0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
36bc0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
36bd0 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
36be0 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
36bf0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
36c00 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
36c10 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
36c20 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
36c30 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
36c40 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
36c50 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
36c60 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
36c70 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
36c80 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
36c90 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
36ca0 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
36cb0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
36cc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
36cd0 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
36ce0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
36cf0 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
36d00 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
36d10 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
36d20 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
36d30 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
36d40 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
36d50 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
36d60 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
36d70 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
36d80 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
36d90 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
36da0 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
36db0 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
36dc0 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
36dd0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
36de0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
36df0 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
36e00 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
36e10 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
36e20 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
36e30 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
36e40 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
36e50 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
36e60 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
36e70 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
36e80 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
36e90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36ea0 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
36eb0 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
36ec0 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
36ed0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36ee0 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
36ef0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
36f00 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
36f10 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
36f20 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
36f30 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
36f40 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
36f50 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
36f60 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
36f70 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
36f80 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
36f90 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
36fa0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
36fb0 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
36fc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
36fd0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
36fe0 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
36ff0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
37000 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
37010 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
37020 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
37030 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
37040 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
37050 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
37060 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
37070 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
37080 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
37090 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
370a0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
370b0 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
370c0 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
370d0 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
370e0 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
370f0 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
37100 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
37110 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
37120 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
37130 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
37140 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
37150 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
37160 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
37170 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
37180 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
37190 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
371a0 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
371b0 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
371c0 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
371d0 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
371e0 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
371f0 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
37200 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
37210 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
37220 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
37230 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
37240 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
37250 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
37260 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
37270 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
37280 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
37290 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
372a0 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
372b0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
372c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
372d0 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
372e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
372f0 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
37300 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
37310 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
37320 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
37330 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
37340 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
37350 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
37360 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
37370 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
37380 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
37390 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
373a0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
373b0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
373c0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
373d0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
373e0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
373f0 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
37400 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
37410 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
37420 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
37430 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
37440 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
37450 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
37460 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
37470 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
37480 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
37490 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
374a0 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
374b0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
374c0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
374d0 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
374e0 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
374f0 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
37500 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
37510 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
37520 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
37530 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
37540 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
37550 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
37560 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
37570 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
37580 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
37590 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
375a0 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
375b0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
375c0 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
375d0 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
375e0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
375f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
37600 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
37610 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
37620 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
37630 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
37640 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
37650 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
37660 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
37670 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
37680 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
37690 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
376a0 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
376b0 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
376c0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
376d0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
376e0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
376f0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
37700 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
37710 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
37720 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
37730 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
37740 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
37750 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
37760 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
37770 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
37780 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
37790 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
377a0 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
377b0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
377c0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
377d0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
377e0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
377f0 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
37800 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
37810 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
37820 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
37830 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
37840 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
37850 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
37860 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
37870 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
37880 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
37890 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
378a0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
378b0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
378c0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
378d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
378e0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
378f0 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
37900 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
37910 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
37920 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
37930 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
37940 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
37950 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
37960 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
37970 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
37980 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
37990 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
379a0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
379b0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
379c0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
379d0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
379e0 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
379f0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
37a00 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
37a10 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
37a20 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
37a30 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
37a40 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
37a50 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
37a60 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
37a70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37a80 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
37a90 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
37aa0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
37ab0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
37ac0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
37ad0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
37ae0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
37af0 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
37b00 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
37b10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37b20 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
37b30 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
37b40 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
37b50 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
37b60 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
37b70 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
37b80 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37b90 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
37ba0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
37bb0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
37bc0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
37bd0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
37be0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
37bf0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
37c00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
37c10 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
37c20 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
37c30 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
37c40 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
37c50 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
37c60 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
37c70 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
37c80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
37c90 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
37ca0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
37cb0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
37cc0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
37cd0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
37ce0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
37cf0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
37d00 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
37d10 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
37d20 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
37d30 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
37d40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
37d50 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
37d60 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
37d70 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
37d80 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
37d90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
37da0 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
37db0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
37dc0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
37dd0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
37de0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
37df0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
37e00 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
37e10 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37e20 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
37e30 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
37e40 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
37e50 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
37e60 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
37e70 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
37e80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
37e90 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
37ea0 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
37eb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
37ec0 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
37ed0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
37ee0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
37ef0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
37f00 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
37f10 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
37f20 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
37f30 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
37f40 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
37f50 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20 2f            1    /
37f60 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33  * IMP: R-37514-3
37f70 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20  5566 */.#define 
37f80 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20  SQLITE_UTF16LE  
37f90 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d        2    /* IM
37fa0 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37  P: R-03371-37637
37fb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
37fc0 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20  TE_UTF16BE      
37fd0 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    3    /* IMP: R
37fe0 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a  -51971-34154 */.
37ff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
38000 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
38010 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
38020 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
38030 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
38040 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
38050 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20    /* Deprecated 
38060 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
38070 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
38080 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
38090 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
380a0 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
380b0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
380c0 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ion Flags.**.** 
380d0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
380e0 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65  may be ORed toge
380f0 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a  ther with the .*
38100 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
38110 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
38120 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65  encoding] as the
38130 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
38140 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
38150 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
38160 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
38170 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
38180 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
38190 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
381a0 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  n_v2()]..*/.#def
381b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52  ine SQLITE_DETER
381c0 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30  MINISTIC    0x80
381d0 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
381e0 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
381f0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
38200 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
38210 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
38220 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
38230 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
38240 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
38250 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
38260 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
38270 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
38280 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
38290 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
382a0 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
382b0 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
382c0 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
382d0 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
382e0 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61  ons.  To encoura
382f0 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74  ge programmers t
38300 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65  o avoid.** these
38310 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77   functions, we w
38320 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20  ill not explain 
38330 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
38340 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
38350 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
38360 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
38370 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
38380 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
38390 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
383a0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
383b0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
383c0 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
383d0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
383e0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
383f0 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
38400 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
38410 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
38420 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
38430 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
38440 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
38450 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
38460 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
38470 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
38480 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
38490 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
384a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
384b0 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
384c0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
384d0 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20  int64,int),.    
384e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
384f0 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f    void*,sqlite3_
38500 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
38510 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38520 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61  Obtaining SQL Va
38530 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
38540 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
38550 0a 2a 2a 20 3c 62 3e 53 75 6d 6d 61 72 79 3a 3c  .** <b>Summary:<
38560 2f 62 3e 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  /b>.** <blockquo
38570 74 65 3e 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  te><table border
38580 3d 30 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 30  =0 cellpadding=0
38590 20 63 65 6c 6c 73 70 61 63 69 6e 67 3d 30 3e 0a   cellspacing=0>.
385a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71  ** <tr><td><b>sq
385b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
385c0 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74  </b><td>&rarr;<t
385d0 64 3e 42 4c 4f 42 20 76 61 6c 75 65 0a 2a 2a 20  d>BLOB value.** 
385e0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
385f0 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 3c  e3_value_double<
38600 2f 62 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64  /b><td>&rarr;<td
38610 3e 52 45 41 4c 20 76 61 6c 75 65 0a 2a 2a 20 3c  >REAL value.** <
38620 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65  tr><td><b>sqlite
38630 33 5f 76 61 6c 75 65 5f 69 6e 74 3c 2f 62 3e 3c  3_value_int</b><
38640 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 33 32 2d  td>&rarr;<td>32-
38650 62 69 74 20 49 4e 54 45 47 45 52 20 76 61 6c 75  bit INTEGER valu
38660 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 3c 62 3e  e.** <tr><td><b>
38670 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
38680 74 36 34 3c 2f 62 3e 3c 74 64 3e 26 72 61 72 72  t64</b><td>&rarr
38690 3b 3c 74 64 3e 36 34 2d 62 69 74 20 49 4e 54 45  ;<td>64-bit INTE
386a0 47 45 52 20 76 61 6c 75 65 0a 2a 2a 20 3c 74 72  GER value.** <tr
386b0 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74 65 33 5f  ><td><b>sqlite3_
386c0 76 61 6c 75 65 5f 70 6f 69 6e 74 65 72 3c 2f 62  value_pointer</b
386d0 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 50  ><td>&rarr;<td>P
386e0 6f 69 6e 74 65 72 20 76 61 6c 75 65 0a 2a 2a 20  ointer value.** 
386f0 3c 74 72 3e 3c 74 64 3e 3c 62 3e 73 71 6c 69 74  <tr><td><b>sqlit
38700 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 3c 2f 62  e3_value_text</b
38710 3e 3c 74 64 3e 26 72 61 72 72 3b 3c 74 64 3e 55  ><td>&rarr;<td>U
38720 54 46 2d 38 20 54 45 58 54 20 76